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�
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.
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
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
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 ]
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
Joined: Jul 11, 2001
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?
Joined: Jul 11, 2001
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.
- 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...
Joined: Jan 29, 2003
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
Joined: Oct 20, 2007
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 ]