Coding Standards

[Javini Javono]

Hi,
Here are a few questions I have about Sun's Java Code Conventions article.
Question 1
Section 3.1.1 says that all source files should begin with Beginning Comments
containing the class name, version information, data, and copyright notice.
George, since you scored 100, did you use Beginning Comments?

Question 2
Section 4, on indentation, states:
1. Four spaces should be used as the unit of indentation. The exact construction
of the indentation (spaces verse tabs) is unspecified.
2. Tabs must be set exactly every 8 spaces (not 4).
From item 1, if I have a tab equivalent to four spaces, then it seems that
I violate the condition in item 2. Is Sun basically saying that I must not use any
tabs in the source file, and only use spaces?

Question 3
It would make a lot of sense to use an automated tool to incorporate all the rules
in this document: Sun's Java Code Conventions. I've done a little experimenting
with some of these free reformatting tools, but none of them, that I am aware of,
give you the ability to precisely follow all the rules, though they come very close.
What tools do you recommend that can be used to take a source code file
and reformat it to precisely follow Sun's Java Code Conventions?
Thanks,
Javini Javono

[Mark Spritzler]

Yes, then indentation of code is 4 spaces. By using spaces instead of tabs you make sure that it is always indented 4 spaces, because some text editors might have their tab setting to more or less than 4 spaces. In some of the better text editors, it allows you to use tab and converts the tabs to spaces when saving. TextPad has this feature.
My best suggestion for following Sun's standards are to read them and follow them while you code, instead of hoping that a tool will work completely.
I would say follow the 4 spaces, good naming conventions, Javadoc specs and you will do fine.
Mark

[George Marinkovich]

Hi Javini,

Originally posted by Javini Javono:

Question 1
Section 3.1.1 says that all source files should begin with Beginning Comments
containing the class name, version information, data, and copyright notice.
George, since you scored 100, did you use Beginning Comments?

Yes, I had a javadoc comment immediately before the class name in every source file (I only had one class (not counting inner classes) per source file). I didn't include the class name because that seems sort of silly as the javadoc comment appears immediately before the class declaration.
The first sentence of a javadoc comment has a special status since it will appear as the sole comment in summary section of the javadoc documentation. To help me remember this I always included a blank javadoc line after the first sentence to remind me that the first sentence would stand alone in the summary section. For example,

    /**
     * This is the first sentence.
     *
     * This is the rest of the javadoc comment text.
     *
     * @author George Marinkovich
     * @version 1.0 11-Dec-2003
     */

I used the @author and @version tags everytime, the @see tag if I felt it was appropriate.

Question 2
Section 4, on indentation, states:
1. Four spaces should be used as the unit of indentation. The exact construction
of the indentation (spaces verse tabs) is unspecified.
2. Tabs must be set exactly every 8 spaces (not 4).
From item 1, if I have a tab equivalent to four spaces, then it seems that
I violate the condition in item 2. Is Sun basically saying that I must not use any
tabs in the source file, and only use spaces?

I used 4 spaces of indentation. I used 8 spaces on the following lines if a long line had to be continued to following lines. My editor, TextPad, allowed automatic conversion of tabs to spaces so I was able to use tabs knowing that they would be converted to 4 spaces when the file was saved.

Question 3
It would make a lot of sense to use an automated tool to incorporate all the rules
in this document: Sun's Java Code Conventions. I've done a little experimenting
with some of these free reformatting tools, but none of them, that I am aware of,
give you the ability to precisely follow all the rules, though they come very close.
What tools do you recommend that can be used to take a source code file
and reformat it to precisely follow Sun's Java Code Conventions?

Other than TextPad, the only tool I used was Sun's DocCheck utility to discover any problems with my javadoc documentation. I highly recommend DocCheck. I concur with Mark that the best way to ensure good documentation is to do it as you go along. I also took a final pass through all the code fixing any indentation problems. Running DocCheck was a great way to find out about any javadoc problems. Also, actually reading the generated javadoc documentation was helpful in spotting some errors. Also, TextPad had a spell check facility that seemed to understand the format of Java comments so it located any misspellings in the Java comments.

[Andrew Monkhouse]

Hi Javini,

Question 1
Section 3.1.1 says that all source files should begin with Beginning Comments
containing the class name, version information, data, and copyright notice.
George, since you scored 100, did you use Beginning Comments?

I did exactly the same as George - I had begining comments, but left out the class name.

Question 2
Section 4, on indentation, states:
1. Four spaces should be used as the unit of indentation. The exact construction
of the indentation (spaces verse tabs) is unspecified.
2. Tabs must be set exactly every 8 spaces (not 4).
From item 1, if I have a tab equivalent to four spaces, then it seems that
I violate the condition in item 2. Is Sun basically saying that I must not use any
tabs in the source file, and only use spaces?

Take a look at the following code:

class BlahBlah {
    // there are four spaces at the start of this line
    if (somecheck) {
        // there could be four spaces or a tab at the start of this line
    }
}

As you can see, standard indentation is four spaces. But where lines are indented several levels it might be annoying to type that many spaces, so the Sun coding convention does allow you to use tabs as long as the tabs are eight spaces - so you cannot use it as your standard indentation, but you can use it on a subsequent indentation.
I used to use UltraEdit (back in my Microsoft PC days), which allowed me to type a tab which was automagically converted into 8 spaces.

Question 3
It would make a lot of sense to use an automated tool to incorporate all the rules
in this document: Sun's Java Code Conventions. I've done a little experimenting
with some of these free reformatting tools, but none of them, that I am aware of,
give you the ability to precisely follow all the rules, though they come very close.
What tools do you recommend that can be used to take a source code file
and reformat it to precisely follow Sun's Java Code Conventions?

I agree with Mark and George - writing code the correct way is far better than hoping that a reformatter will get it right.
I used CheckStyle to validate my coding in general, and Sun's DocCheck utility to check my documentation.
Regards, Andrew
[ February 25, 2004: Message edited by: Andrew Monkhouse ]

[Javini Javono]

Hi,
Thanks for all your comments.
Just to avoid confusion, the first text block you see in the
code below is what Sun calls a "Beginning Comment".
I take it that you all do not use these, and I will not either.

/*
* @(#)Blah.java 1.82 99/03/18
*
* Copyright (c) 1994-1999 Sun Microsystems, Inc.
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All Rights Reserved.
*
* This software is the confidential and proprietary information of Sun
* Microsystems, Inc. ("Confidential Information"). You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with Sun.
*/
package java.blah;
import java.blah.blahdy.BlahBlah;
/**
* Class description goes here.
*
* @version 1.82 18 Mar 1999
* @author Firstname Lastname
*/
public class Blah extends SomeClass {

Instead, I will use this, which is exactly the same as above, but with no
beginning comments before the package statement.

package java.blah;
import java.blah.blahdy.BlahBlah;
/**
* Class description goes here.
*
* @version 1.82 18 Mar 1999
* @author Firstname Lastname
*/
public class Blah extends SomeClass {

Though I may modify the class Javadoc comments to conform to the
ideas put forth by George and seconded by Andrew.
Thanks,
Javini Javono

[Javini Javono]

Hi,
Thanks again for your responses.
Concerning spaces and tabs, I now understand what Sun was saying (I think,
that is, you can use a tab, but it must line up on 8 multiples).
When I'm ready to deliver the software, I'll convert all leading line tabs
to four spaces using JEdit's plug-in called WhiteSpace.
I could tell JEdit simply to use a "soft tab", i.e., typing the tab makes
four spaces, but, unfortunately, JEdit is not smart enough to delete
this "soft tab" with one press of the delete or backspace key.
(Interestingly enough, Apple's xcode is smart enough, but I need to
develop using both xcode and JEdit since each environment has it's
pluses and minuses).
In summary, my software will be delivered never containing the \t
(tab) character, and each "tab" will be four spaces.
But, during development, my software files will use the \t character
for only one reason: JEdit does not yet delete a soft tab with one
stroke of the delete or backspace key, but instead requires four presses
of this key.
Also, during development, I have to get out of the habit of using
tabs within a line of code, as there is no extant software I am aware
which correctly inserts the correct number of spaces for the tabs,
such as after a variable declaration but before the line comment: // comment.
Ammendment:
Actually, now that I think about it, tabs are way too common not to
use them during development. So, I'll write my own software to
go through every source file and correctly replace every \t
with the correct number of spaces. For instance, leading tabs would
be replaced by " " four blanks, but interior line tabs would need
to be calculated to determine how many spaces to insert.
Again, if I was only using xcode, then everything would be fine,
but JEdit I also want to use, so \t has to be used during development
(I can't stand backspacing 4 times, or spacing out to write the variable
name, and spacing again to add the line comment, when tabs were
invented for this purpose).
Thanks,
Javini Javono
[ February 25, 2004: Message edited by: Javini Javono ]

[Javini Javono]

Hi,
Again, thanks for your replies.
Concerning auto-matic formatters, such as the plug-ins for JEdit
called Jalopy (which seems very precise, but cannot handle
the following case: alligning "//" or "/* */" comments that exist
during an if-else block, for instance, at the ends of lines),
I will do as you all suggest: write the code out properly formatted
first, and not expect it to do everything for me;
for instance, it probably doesn't really know where to divide a
line properly per Sun's specifications.
But, I'll also use Jalopy to find glaring errors which I may overlook.
So, I'll use the JEdit plugin JDiff, and then compare the two files:
one I created by hand, and one automatically formatted, and see
if I missed anything. This is sort of like going to a chess tournament,
then coming home and feeding the position into your computer to
see if there were any glaring oversights that either side missed during
the heat of battle.
Thanks,
Javini Javono
[ February 25, 2004: Message edited by: Javini Javono ]

[George Marinkovich]

Hi Andrew,

Originally posted by Andrew Monkhouse:
I used CheckStyle to validate my coding in general, and Sun's DocCheck utility to check my documentation.

CheckStyle is amazing! I wish I had know about it earlier. I ran it on my project code (using sun_checks.xml configuration file) and it found 684 style problems! I fixed all the problems and it was a very interesting learning experience. There were a few areas where I disagree with the checks in sun_checks.xml.
For example:

class Example {
    private int field;
    Example(int field) {
        this.field = field;
    }
}

Even though the parameter field is hiding the member variable of the same name I think this is a nice idiom.
It complains about redundant throws, so in the following code it doesn't think RemoteException should be listed because it is a subclass of an IOException. Their argument is that the client should only have to handle IOException. I like seeing both exceptions in the throws list.

    /**
     * Reads a record from the file.
     * <p>
     * Note: unless this method is called in a locked context (that is,
     * after a lock and before an unlock), dirty reads are possible.  To
     * eliminate the dirty read problem simply call this method in the
     * manner described in the class comment.
     *
     * @param recNo record number to read
     * @return an array where each element is a record field
     * @throws IOException     if the requested record can't be found.
     * @throws RemoteException if there is a communication-related
     *                         problem.
     */
    public final String[] read(final int recNo)
            throws IOException, RemoteException {
        return db.read(recNo);
    }

And then it doesn't appreciate the beauty of nested blocks:

    private JPanel buildInputPanel() {
        // Input Panel
        JPanel inputPanel = new JPanel();
        {
            final int top    = 15;
            final int left   =  5;
            final int bottom = 10;
            final int right  =  5;
            inputPanel.setBorder
                    (new EmptyBorder(top, left, bottom, right));
        }
    }

Fortunately, the sun_checks.xml can be modified very easily. I just removed the AvoidNestedBlocks module and modified the HiddenField and RedundantThrows as follows:

<module name="HiddenField">
    <property name="tokens" value="VARIABLE_DEF"/>
</module><module name="RedundantThrows">
    <property name="allowSubclasses" value="true"/>
</module>

The only problem I had is that I was never able to get rid of the "Unable to get class information for RecordNotFoundException." type errors, even though I specified a classpath to the *.class files.

java -classpath devProject/classes -jar \
/checkStyle-3.3/checkstyle-all-3.3.jar \ 
-c /checkStyle-3.3/docs/sun_checks_modified.xml \
-r devProject/code

Any idea why?
Anyway it is a fantastic tool, thanks for bringing it to my attention.

[Andrew Monkhouse]

Hi George,
One of the nice things about CheckStyle is that the creators have integration tools for most IDEs. So you don't even have to drop to the command line to run it!
I don't know why you are having problems with the RecordNotFoundException. I will say that your example command line is telling the JVM where your RecordNotFoundException is, which should be unnecessary.
I used the following ant task to get checkstyle to recognise all my classes correctly:

  <taskdef resource="checkstyletask.properties"/>
  <target name="checkstyle">
    <checkstyle config="/opt/checkstyle-3.0/docs/sun_checks.xml">
      <fileset dir="src/suncertify" includes="**/*.java"/>
    </checkstyle>
  </target>

Regards, Andrew

[Nathaniel Stoddard]

I found that the (my) grader(s) aren't as picky about coding standards as they claim to be. I simply did the relevant indentation and file header, all javadocs, but that's it.
My functions were all mismatched (not organized according to scope, or similarity). I even had to go through my javadocs at one point (okay, alot of points) to rewrite them because they were very bad IMO.
But in the end, I got a 100 on documentation too. In fact, documentation was my biggest stress before turning in my submission, but it didn't really matter too much.
IMO, you can spend a solid year trying to conform to all the coding conventions, but if you spend a good effort adhering to the obvious ones they will look for, and spend the rest of the time doing other stuff (like making sure your locking mechanism is actually thread-safe), then I think you'll come out much better for it all.
BUT, like I hinted at in the beginning, that may have been an exception for my grader alone.

[Javini Javono]

Hi George,


The only problem I had is that I was never able to get rid of the "Unable to get class
information for RecordNotFoundException." type errors, even though I specified a
classpath to the *.class files.


I was having a similar problem. Here is how my system is set up so that it works.
I execute the task from the directory that is at the root of all my packages (which
in this case is just above the suncertify folder).

I compile all my .java files so that they co-exist with their compiled .class files.

I then used the following .sh command file in UNIX (i.e., Mac OS X):

cd ..
cd code
#  Options for checkstyle:
#   -c    The check configuration file to use.
#   -f    Sets the output format. (plain|xml). Defaults to plain
#   -n    Loads the package names file
#   -o    Sets the output file. Defaults to stdout
#   -p    Loads the properties file
#   -r    Traverse the directory for source files
#  
#  The . at the beginning is so that the software will not report that it can't
#  find the class files for my home-grown exceptions;  also, you need to have
#  the files compiled so that the class files are indeed extant prior to
#  running.
java -cp .:/Users/me/checkstyle-3.4/checkstyle-all-3.4.jar                      \
     com.puppycrawl.tools.checkstyle.Main                                      \
     -c /Users/me/Project/sun_checks.xml                                        \
     -f plain                                                                  \
     -o /Users/me/Project/docs/javadoc/CheckStyleOutput                         \
     -r /Users/me/Project/code/suncertify
#  
rm /Users/me/Project/docs/javadoc/CheckStyleOutputReduced
java -cp /Users/me/java otherPrograms.CheckStyleCleaner >/Users/me/Project/docs/javadoc/CheckStyleOutputReduced
rm /Users/me/Project/docs/javadoc/CheckStyleOutput
#  
cd ..
cd com
pwd

Thanks,
Javini Javono