aspose file tools*
The moose likes Beginning Java and the fly likes comments in Java Class Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Java 8 in Action this week in the Java 8 forum!
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "comments in Java Class" Watch "comments in Java Class" New topic
Author

comments in Java Class

Abdul Kader
Ranch Hand

Joined: Apr 11, 2007
Posts: 115
How can we give a comment in between methods so that other developer can understand the functionality easily? I do follow some methods to do that, however I am interested to know any standard way to do this. Because already have javadocs which will help us to create the documentation for the java class, like wise is there any way comments in Java Class´┐Ż
Rob Spoor
Sheriff

Joined: Oct 27, 2005
Posts: 19556
    
  16

There are three types of comments in Java:
- single line comments start with //, and end when the line ends
- multi line comments start with /* and end with */
- JavaDoc comments start with /** and end with /*

Now you can use any of these comment types anywhere in your code. JavaDoc just has special meaning, but it can still be placed inside methods. It just won't have any JavaDoc created then, but it is possible.


SCJP 1.4 - SCJP 6 - SCWCD 5 - OCEEJBD 6
How To Ask Questions How To Answer Questions
Cameron Wallace McKenzie
author and cow tipper
Saloon Keeper

Joined: Aug 26, 2006
Posts: 4968

Remember, JavaDoc is for people using the API, not for developers maintaining the code. Those are two vastly different interests at play there.

Always comment your code. If people say nothing else nice about you, at least they can say that your code is well commented.

I always use /* */ , never //. I have my reasons.

-Cameron McKenzie
Olivier Legat
Ranch Hand

Joined: Nov 17, 2007
Posts: 176

Heys guys. Sorry if this is a bit off the topic but what is a JavaDoc comment actually?


Olly
marc weber
Sheriff

Joined: Aug 31, 2004
Posts: 11343

Originally posted by Olivier Legat:
...what is a JavaDoc comment actually?

Javadoc is the tool that creates documentation in HTML form, like the Java API. The format for javadoc comments basically flags text for inclusion in that HTML documentation.


"We're kind of on the level of crossword puzzle writers... And no one ever goes to them and gives them an award." ~Joe Strummer
sscce.org
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
I like to write a package.html file for JavaDoc. It's a good place to give an overview of a package and the key classes. I usually write one lineer at the class level that describes the purpose of the class. For these two levels I write for someone I'll never meet who bought a jar and the doc but no source code.

I try not to write any other comments. The way to achieve that is to make the code say whatever the comment was going to say. Sometimes I give in and explain why a method might throw an exception, but not often. Run the JavaDoc and think about that unknown person reading it for the first time.

If you're tempted to put a comment on a method or in the middle of a method to explain what the next few lines do, stop and make the code tell the story. Small methods with great names make all the difference.

My current team encourages lots of comments. Reading mature code I find many comments were copy-pasted along with bits of the code, or were not maintained along with the code and they are dead wrong. Many others add absolutely nothing to what JavaDoc can infer from the method signature.

I especially hate this kind of thing that I see all over. It tells me nothing and just gets in the way when I'm reading. If it's even true.


A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
I'm with Stan here. I see writing code that needs a comment as a personal failure. Show me code that needs a comment, and I show you code that can be improved.


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Kelvin Chenhao Lim
Ranch Hand

Joined: Oct 20, 2007
Posts: 513
Originally posted by Ilja Preuss:
I'm with Stan here. I see writing code that needs a comment as a personal failure. Show me code that needs a comment, and I show you code that can be improved.


Comments aren't just for explaining how code works, though. I use comments mainly to explain why I decided to implement a feature or algorithm a particular way. This is especially useful in situations where there's an "obvious" way of doing things that actually turns out to have serious but subtle flaws. If I don't put a comment next to the code in question, it's quite possible that some future zealous but inexperienced programmer will attempt to "optimize" my code using the flawed implementation approach.
[ November 29, 2007: Message edited by: Kelvin Lim ]

SCJP 5.0
Jesper de Jong
Java Cowboy
Saloon Keeper

Joined: Aug 16, 2005
Posts: 13884
    
  10

Originally posted by Ilja Preuss:
I'm with Stan here. I see writing code that needs a comment as a personal failure. Show me code that needs a comment, and I show you code that can be improved.

I don't agree. Sometimes I have to implement some complicated algorithms. In the code, I document the steps of the algorithm with one or two comment lines for each step.

Sometimes things are just not so simple that the code can easily be written so that it is self-explanatory.


Java Beginners FAQ - JavaRanch SCJP FAQ - The Java Tutorial - Java SE 7 API documentation
Scala Notes - My blog about Scala
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
I draw a distinction between JavaDoc comments and other comments. I will often write up decent JavaDoc comments for public and protected methods, assuming the project is one where there's at least a reasonable chance that people will look at the JavaDoc as opposed to the source. But even there I will not comment on things that are obvious from the name, and I will put effort into using names that make things obvious. Also if I'm overriding a method, I will typically let the base method's JavaDoc speak for itself, unless the overriding method has differences that the user needs to be aware of. I'm also not a fan of really long class and method names, and so there is often additional info that a user should have, that does not fit nicely into a name. In this case, sure, write up a JavaDoc comment so that someone can use the code effectively without browsing the source.

For non-JavaDoc comments, I favor a minimal approach, often no comments at all. And if I feel the need for a comment, I will certainly consider whether there's a way to write the code more clearly instead. But sometimes that's just not satisfactory, and I don't lose sleep over it if I find a comment to be the best solution. Kelvin cited a common reason I have for comments: explaining why some other approach was not used. TODO: comments are another common use, though ideally they don't appear in a finished product. (In the hypothetical scenario that you ever have code that is truly finished.) For Jesper's example of complicated algorithms, I will usually try to break the steps into separate methods with decriptive names. But still, sometimes there is still info that's best communicated by a comment; so be it.


"I'm not back." - Bill Harding, Twister
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Kelvin Lim:

Comments aren't just for explaining how code works, though. I use comments mainly to explain why I decided to implement a feature or algorithm a particular way. This is especially useful in situations where there's an "obvious" way of doing things that actually turns out to have serious but subtle flaws. If I don't put a comment next to the code in question, it's quite possible that some future zealous but inexperienced programmer will attempt to "optimize" my code using the flawed implementation approach.


Most often, those "whys" can actually be expressed in unit tests, which has a whole bunch of advantages over comments. Failing that, I would still try to express it directly in the production code.

Do you have an example?
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Jesper Young:
Sometimes I have to implement some complicated algorithms. In the code, I document the steps of the algorithm with one or two comment lines for each step.


Extract Method helps a lot, here.


Sometimes things are just not so simple that the code can easily be written so that it is self-explanatory.


Two observations:

- most often when things aren't simple, I finally notice that they aren't simple because I failed to *make* them simple

- even if I finally have to give up because I don't find a way to make it simpler, trying hard still was worth it. And it's astonishing how often I still *do* find a way when I look at the code half a year later. I take that as a sign that I'm still learning, which I tend to think of as a good thing...
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
I agree with explaining why some times. The only example I can think of in recent years, though, is one that says "the current algorithm replaced a much more obvious recursive design because the recursive one blew the stack." It's mostly a reminder not to refactor back to the "obvious" recursive design.

And I wouldn't claim to be able to make everything clear to someone who doesn't have the source code through good naming alone. I have this comment in current code:

(HTML formatting removed)
Kelvin Chenhao Lim
Ranch Hand

Joined: Oct 20, 2007
Posts: 513
Originally posted by Ilja Preuss:
Most often, those "whys" can actually be expressed in unit tests, which has a whole bunch of advantages over comments.

No doubt, but I don't want someone to waste time rewriting an algorithm only to discover their error later upon running unit tests. Moreover, unit tests don't really tell a programmer why their modified code failed. The programmer might just think that he/she made a mistake in the new implementation, and then proceed to waste even more time attempting to debug it--when a simple comment could have easily preempted all of this frustration and cost.

Do you have an example?[/QB]

I have lots of real-life examples from my work, though these tend to be more complex or domain-specific than the typical toy examples one would use for educational purposes. For legal reasons, I'm unable to share my project's code, but I can describe one simple example that many OpenGL programmers should be familiar with: a polygon drawing algorithm. As you may know, the OpenGL API provides a commonly-used rendering method that can be called with a variety of graphical primitives, including polygons. To a relatively new OpenGL programmer who has used this method for drawing other primitives (e.g. points and lines), this would be the "obvious" approach for implementing any algorithm that involves polygon drawing. However, it turns out that the OpenGL API method in question has a significant limitation: it only correctly renders convex polygons (as opposed to concave polygons). This is good enough for many purposes, so it's not unreasonable for an OpenGL programmer to be unaware of this limitation. However, if your application does need to render concave polygons, then you must instead use a much more involved (and somewhat non-intuitive) sequence of operations to render the polygons correctly.

Early on in my OpenGL work, I myself made the mistake of attempting to "optimize" one of these algorithms by replacing it with the "obvious" implementation approach. Fortunately, I discovered my error during testing, and (thanks to a couple of Google searches) I was able to quickly learn the reason why my approach was flawed. Nonetheless, I had already wasted a significant amount of time refactoring a rather large chunk of code in the interest of performance--only to abandon my changes in the end.

And, yes, one may counter-argue that this particular error can be largely blamed on the programmer's failure to read the fine print in the OpenGL API documentation. But I don't think it's unreasonable to add a comment to help out a fellow programmer, especially when the erroneous line of reasoning seems rather natural. Moreover, not all of these issues are easy to anticipate; for instance, I've sometimes had to add seemingly redundant OpenGL operations as workarounds for bugs/idiosyncrasies in my clients' video drivers (which we can't change). Without inline comments to document these reasons, another programmer may delete the "redundant" operations.

Granted, perhaps these scenarios only occur when one has to deal with lower-level APIs like OpenGL. But that's the nature of real-world production code in many domains. Sometimes, no matter how hard one strives to write elegant, self-explanatory code (and trust me, I'm a huge advocate for such efforts), a correct and efficient algorithm just cannot be written without contradicting one's intuitions. And I strongly believe that if you have to write such code, then you'd better make sure you document your decision properly in a place where someone reviewing your code can see it easily!
[ November 30, 2007: Message edited by: Kelvin Lim ]
 
 
subject: comments in Java Class
 
Similar Threads
comments in Java Class
class defined inside an interface
HELP: Suitable datastructure for classes
Suitable datastructure for classes...?
How to enable commenting into pdf files using java?