This week's giveaway is in the Android forum.
We're giving away four copies of Android Security Essentials Live Lessons and have Godfrey Nolan on-line!
See this thread for details.
The moose likes Java in General and the fly likes What's your commenting strategy? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Java » Java in General
Bookmark "What Watch "What New topic
Author

What's your commenting strategy?

Frank Carver
Sheriff

Joined: Jan 07, 1999
Posts: 6920
I've been writing Java for at least two years now, but I keep changing my mind on how best to comment my code. This has recently been brought to a head as I've started a university postgraduate course on Java and the views of my
tutor don't quite line up with my current usage.
How do the rest of you comment your Java code? Do you put *full* JavaDoc for everything, even obvious member variables and method parameters? Do you use JavaDoc at all?
Do you prefer /**/ or // comments? Do you use standardised "header blocks" for classes and/or methods, and if so what do they contain? etc. etc.
I'd just like to get some idea what others are doing before I get into an email battle with my tutor or the course organisers. All input welcome, especially (short!) examples.
Frank.


Read about me at frankcarver.me ~ Raspberry Alpha Omega ~ Frank's Punchbarrel Blog
paul wheaton
Trailboss

Joined: Dec 14, 1998
Posts: 20494
    ∞

I just started with a new Java team where full JavaDoc is required.
I think this is overkill. I'm a firm believer of self documenting code. If you have a string class that has the method "void append(MyString S);" I think anyone should have a clear idea of what it does.
I use the // a lot. I use /* */ only to temporarily comment out a block of code or to hold a huge comment spanning more than three lines.

permaculture Wood Burning Stoves 2.0 - 4-DVD set
paul wheaton
Trailboss

Joined: Dec 14, 1998
Posts: 20494
    ∞

Oh - one last tidbit. On my wall I have a list of 12 programming pearly to live by. The very first one says "Debug only code - comments can lie".
One more tidbit. In the last project where I carefully maintained full JavaDoc, when I made changes to the code, the JavaDoc maintenance took twice as long as the coding. The temptation to not update the JavaDoc portion was immense. I could see how a programmer who may lack discipline would not have updated the JavaDoc comments.
Matt Midcap
Sheriff

Joined: Jan 07, 1999
Posts: 440
I agree with Paul that simplest is best, however - I've been requried to use JavaDoc as well.
Since I've been required to do it since I've started Java (at school), and everyone knows what it is, it's probably what I'll be sticking to in the long run.
[This message has been edited by Matt Midcap (edited January 08, 1999).]


Best Regards,<br />Matt Midcap
SimonBurton
Greenhorn

Joined: Jan 07, 1999
Posts: 4
I like this "self documenting code". This is why we aren't still writing in assembler. use whole words for variables etc.
what about javadoc generating an HTML version of your code on the end of the usual javadoc with sensible conventions for where the hyperlinks go to. you could end up with mostly blue code
Anonymous
Ranch Hand

Joined: Nov 22, 2008
Posts: 18944
I use JavaDoc comments, and my job requires them as well. There was a pretty cool JavaDoc tool called DocWizard that was posted up on the JavaLobby site, but I didn't manage to write it down. I'm trying to locate it, as I have a good bit of Java Doc to do.
The one thing about this kind of tool, and given Java parsers aren't hard to find (i.e. cheap), tools to help manage the Java doc comments will get better I think. For instance, you should be able to automatically generate the JavaDoc comments, and all of the proper param and return and exception tags IMHO. In addition, it should put a default comment in for getters and setters.
I personally would like one that strips out the JavaDoc temporarily while I'm coding/debugging/maintaining, etc, then puts it back in.
MHO.
Doug Gschwind
Ranch Hand

Joined: Dec 17, 1998
Posts: 44
Please be seated for this one.
<soapbox>
To what level you embrace the use of javadoc style comments appears to me to be too subjective to generalize. I have seen developers who prefer to read source code to determine behavior for themselves (probably previously burned by trusting incorrect comments), yet I prefer to read the description and intent of an interface (e.g. JDK API) while designing/implementing to it. I really think the only way to proper due diligence is to look at the benefits you will realize, on a project by project basis, in terms of Javadoc style comments, before dictating its use.
In my opinion, the information provided in a javadoc style comment block is required to be provided by the class designer, whether javadoc style comments are used or not. The behavior and intent of a method (e.g. description, meanings of parameter(s) and their legal value lists, preconditions, under what conditions an exception will be thrown, what information is returned, other methods to reference, etc.) or class needs to be stated. You simply incur the additional overheard of making it javadoc compliant.
In Paul's example, String append(String s), there is clearly little value that additional comments will add, whether they are in javadoc style or not. However, if the interface is changed to String append(), what is being appended? That needs to be advertised to the class consumer. The distinction boils down to how obvious the interface is. Unfortunately, "obvious" can be another subjective area.
To me, the most compelling situation to use javadoc style comments is when you fully plan to deploy your software sans source (only .class files or .zip file) with accompanying documentation. If you have other plans, it appears to me that the decision requires you to do more homework. Again, what benefit will the organization or other developers (in other organizations) realize in spending the time to properly write javadoc style comments?
Of course, I like the idea of writing full javadoc style comments right from the git go, a'la Kramer. That way, if your classes do get deployed as a class library, internally or externally, you have already positioned yourself to properly accommodate your consumers. However, that positioning does come at a cost.
If you choose to go with full javadoc style comments {assuming that very obvious interfaces as in String append(String toAppend) do not require any comment block}, consider the other things you should do for accountability:
1. You may have to write your comments from scratch unless you have a way to forward engineer your designs into javadoc compatible source code as Charles B. suggests.
2. Run your code through javadoc and use your browser of choice to verify that the generated .html file(s) have the intended information in the right places.
3. Your code review/inspection team should now probably review the .html pages as well as their hopefully unbiased review will catch some things that you as the designer inadvertently missed.
This could be a lot of work overall, but lets keep in mind that documentation is a large and required part of your job if you consider yourself a software developer. The fact that it takes you twice as long to update comments, as it does to make the software change those comments describe, is terribly irrelevant in my opinion. A complex piece of software needs documentation.
Regarding self-documenting code. All code is self-documenting. If you are looking at the code that you are attempting to redesign, fix, or maintain, the truth sits in front of your eyes. However, you would have a difficult time dealing with, say, the JDK if it were sans javadoc style comments. I believe self-documenting code is fine in relatively simple methods where additional comments add nothing for the reader. I don't think forcing the reader to read your self documenting code is good practice. The reason being is that forcing the reader to read source code can slow down their productivity immensely. Hey, we are all smart and good at what we do, and we could operate that way. It just does not make good business sense 100% of the time.
Sorry for the dissertation.
</soapbox>
You may now move freely about the cabin.
As I said, I prefer the use of full javadoc style comments, except where the interface being described is very obvious to the consumer.
On non-obvious methods, the description, behavior, and intent is necessary. I also fully advocate the use of @param, @return, @exception, and @see tags. I also prefer to have a preconditions section if an input argument is constrained beyond its data type.
You can get some good advice on writing javadoc style comments at java.sun.com/products/jdk/javadoc/writingdoccomments.html
Anonymous
Ranch Hand

Joined: Nov 22, 2008
Posts: 18944
You make some excellent points, and I tend to agree. It truly depends on the lifecycle of the product, it's exposure to other users who have never seen the code before, and the time at hand.
I like comments for even obvious methods, but I think short is ok.
/** Appends a string to to this string */
String.appendString...
/** Getter for length property */
public int getLength()...
I should also say that many design tools (i.e. UML to Java) will allow commenting of objects by object designers such that (maybe someday?) it might help the object implementer (again, assuming those roles are split, which, in MHO, is good)to fill in the needed code AND act as documentation for that code.
Anonymous
Ranch Hand

Joined: Nov 22, 2008
Posts: 18944
Found two links for JavaDoc Code helpers (IMO, I expect these types of tools to become standard equipment on Object Design tools <UML to Java> and on IDE's). I expect they'll be integrated much like PVCS is today for version management.(or maybe even just encapsulated inside the prodcut).
This one's free(DocWiz):
http://www.mindspring.com/~chroma/docwiz/index.html
This one's NOT ($249 standalone price)
http://www.woodenchair.com/products/DocPlus/docPlus.htm
I've also become interested in Object Modeling tools that do round trip Java engineering. "I have a dream. . .that one day. . ." you know -- my fantasy world -- one product that has UML/Java roundtrip, JavaDoc writing support, and the traditional IDE, all using just the Java source file as it's data (besides the regular project file).
Possible? Likely? Am I high on drugs? (No, just daydreaming) Let me know your thoughts.
Michael Finney
Ranch Hand

Joined: Jan 25, 1999
Posts: 508
I was interested in round trip engineering until I found something out. Some concepts are not reverse engineerable. It's like the concept of 1 + 3 and 2 + 2 both give you 4. However, there was a good reason the model was 1 + 3 and not 2 + 2.
In more OO terms, you'll often find that reverse engineering tools will often give you the general association relationship. However, what if the specialized form of association, aggregation or composition, is the real concept and purpose for why the code is the way it is. Association is technically correct, because it is general enough to cover composition and aggregation. However, who wants to be JUST technically correct?
Just my thoughts,
Michael


Michael Finney - "Always Striving To Serve You Better Every Day"
http://www.smilingsoftwaresolutions.com/
Anonymous
Ranch Hand

Joined: Nov 22, 2008
Posts: 18944
Which tools are you referring to Michael? (I bet it's Rose, and I've had that EXACT same problem. . .and I too don't like it!)
 
It is sorta covered in the JavaRanch Style Guide.
 
subject: What's your commenting strategy?
 
Similar Threads
One last question!!
javadoc style
NX: Bext free style checker ?
JavaDoc <code> or link?
File access from an applet