File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Coding Standards Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Spring in Action this week in the Spring forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Coding Standards" Watch "Coding Standards" New topic
Author

Coding Standards

Javini Javono
Ranch Hand

Joined: Dec 03, 2003
Posts: 286
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
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17257
    
    6

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


Perfect World Programming, LLC - Two Laptop Bag - Tube Organizer
How to Ask Questions the Smart Way FAQ
George Marinkovich
Ranch Hand

Joined: Apr 15, 2003
Posts: 619
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,

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.


Regards, George
SCJP, SCJD, SCWCD, SCBCD
Andrew Monkhouse
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11477
    
  94

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:

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 ]

The Sun Certified Java Developer Exam with J2SE 5: paper version from Amazon, PDF from Apress, Online reference: Books 24x7 Personal blog
Javini Javono
Ranch Hand

Joined: Dec 03, 2003
Posts: 286
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.

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

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
Ranch Hand

Joined: Dec 03, 2003
Posts: 286
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
Ranch Hand

Joined: Dec 03, 2003
Posts: 286
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
Ranch Hand

Joined: Apr 15, 2003
Posts: 619
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:

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.

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

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

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.

Any idea why?
Anyway it is a fantastic tool, thanks for bringing it to my attention.
Andrew Monkhouse
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11477
    
  94

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:

Regards, Andrew
Nathaniel Stoddard
Ranch Hand

Joined: May 29, 2003
Posts: 1258
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.


Nathaniel Stodard<br />SCJP, SCJD, SCWCD, SCBCD, SCDJWS, ICAD, ICSD, ICED
Javini Javono
Ranch Hand

Joined: Dec 03, 2003
Posts: 286
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):



Thanks,
Javini Javono
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Coding Standards