Win a copy of The Java Performance Companion this week in the Performance forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

comments in Java Class

 
Abdul Kader
Ranch Hand
Posts: 115
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Pie
Posts: 20550
57
Chrome Eclipse IDE Java Windows
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Cameron Wallace McKenzie
author and cow tipper
Saloon Keeper
Posts: 4968
1
Hibernate Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 176
Chrome Mac Windows
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Heys guys. Sorry if this is a bit off the topic but what is a JavaDoc comment actually?
 
marc weber
Sheriff
Posts: 11343
Java Mac Safari
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Stan James
(instanceof Sidekick)
Ranch Hand
Posts: 8791
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Kelvin Chenhao Lim
Ranch Hand
Posts: 513
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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 ]
 
Jesper de Jong
Java Cowboy
Saloon Keeper
Pie
Posts: 15364
40
Android IntelliJ IDE Java Scala Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 8791
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 513
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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 ]
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic