• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Ron McLeod
  • Rob Spoor
  • Tim Cooke
  • Junilu Lacar
Sheriffs:
  • Henry Wong
  • Liutauras Vilda
  • Jeanne Boyarsky
Saloon Keepers:
  • Jesse Silverman
  • Tim Holloway
  • Stephan van Hulst
  • Tim Moores
  • Carey Brown
Bartenders:
  • Al Hobbs
  • Mikalai Zaikin
  • Piet Souris

Programmer's Brain - code commenting tips?

 
Greenhorn
Posts: 22
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Are there tips and tricks regarding efficient code commenting, such as it's not overdone but ain't neglected either?
Many thanks.
 
Saloon Keeper
Posts: 24283
167
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Donald Knuth created the term "literate programming". Basically, he wrote out comments, and a utility was supposed to generate code from them.

These days we have JavaDoc and similar systems such as Doxygen. They are descendents of earlier comment-extraction programs mostly harkening back to Unix and its spin-offs. Back in 1986 when the Commodore Amiga PC came out, the system documentation was extracted from code comments using a utility named "Autodoc". In the 1990s I wrote an AWK script that would take specially-formatted comments in C++ code and  spin out Windows Help files.

JavaDoc and its ilk are extremely powerful. Although you'll be most familiar with its use to construct API documentation, some of which is pitifully minimal, Javadoc can, in fact, be used to create complete works of literature with embedded graphics and even full-out multimedia. So you're really best off writing your comments with an eye on how JavaDoc might effectively present them.

But what to put in the comments? Java is a fairly descriptive language and good Java methods are rarely very lengthy. So the best comments won't be how the code is doing thigns, but - abstractly speaking - what it should be doing. I also recommend keeping the Calculus concepts of range and domain in mind (and in the comments). State what the acceptable input values are, what the allowed output values may be and what will happen if those conditions are not met. If you write than in the comments and write the comments before doing the actual code, it will not only avoid surprises on the caller's behalf, it will make it more likely that the code itself will behave properly.
 
Marshal
Posts: 73979
332
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Tim Holloway wrote:. . . the best comments won't be how the code is doing thigns, but . . . what it should be doing. . . .

Apart from what Joshua Bloch, in Effective Java, calls “Document for extension or prohibit it,” or similar, you should remember that documenting “how” may commit your code to always using that particular implementation forever. Look at Objects#hash() as an example; it explains how the hash code is calculated. Fortunately, the link to Arrays#hashCode() keeps quite about the algorithm used, which permits changes if more effective algorithms are found in future. This old version of String#hashCode() keeps quiet about its implementation algorithm, (just as well; according to Joshua Bloch in the same book, it is pretty bad), but more recent versions tell us the algorithm and that precludes future changes.
Note what Tim says about range and domain; they are part of the general contract of the method. If you are going to override methods, they must have a domain (=input) no smaller and a range (=result/output) no larger than the overridden method in order to maintain the Liskov substitution principle. As Bertrand Meyer says (in Object‑Oriented Software Construction), the overriding method may accept more kinds of input than its original form. It mustn't return any output outwith the range of the original outputs, but may return a more refined form of output. One version of the latter is covariant return type; an overriding method may return a subtype of its original method's return type but not its supertype.

And none of this has anything to do with brains, and is probably straying miles from the subject of the original thread.
 
Marshal
Posts: 16591
277
Mac Android IntelliJ IDE Eclipse IDE Spring Debian Java Ubuntu Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Tim Holloway wrote:
But what to put in the comments? Java is a fairly descriptive language and good Java methods are rarely very lengthy. So the best comments won't be how the code is doing thigns, but - abstractly speaking - what it should be doing. I also recommend keeping the Calculus concepts of range and domain in mind (and in the comments). State what the acceptable input values are, what the allowed output values may be and what will happen if those conditions are not met. If you write than in the comments and write the comments before doing the actual code, it will not only avoid surprises on the caller's behalf, it will make it more likely that the code itself will behave properly.


Definitely leave how out of the comments. I would also leave most of the what out of comments and make the code express that clearly enough. Including specifications for valid input values is a good thing.

Comments that explain why the code is written in a certain way are most helpful. I wouldn't try to make the code itself express this but it's important information that will give more context and valuable insights to the reader. The assertion that comments will make it more likely that the code itself will behave properly is debatable though and I would say it will depend largely on the diligence of the author(s) of the code in keeping the comments aligned with the code's actual behavior. In my experience, comments and actual behavior have a greater tendency to diverge rather than stay aligned over time as more hands touch the code.

One more thing to note: comments are listed in Martin Fowler's Refactoring books as a code smell. Comments can indicate that the code is not as clear and expressive as it could be, i.e., the author is trying to explain the how and/or the what of the code.
 
Tim Holloway
Saloon Keeper
Posts: 24283
167
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Junilu Lacar wrote:
Comments that explain why the code is written in a certain way are most helpful. I wouldn't try to make the code itself express this but it's important information that will give more context and valuable insights to the reader. The assertion that comments will make it more likely that the code itself will behave properly is debatable though and I would say it will depend largely on the diligence of the author(s) of the code in keeping the comments aligned with the code's actual behavior. In my experience, comments and actual behavior have a greater tendency to diverge rather than stay aligned over time as more hands touch the code.



No question that code drift can be a real problem. One advantage of short methods is at least you don't have to go flipping up and down to cross-check them. Though that's no guarantee either.

However, it isn't just to keep the coders honest that I'm so much a proponent of explicit statement of ranges, domains, and behaviors. If you're creating a library or even just a shared in-house resource, then you should be producing JavaDocs from that code. That means that people who may never actually see the code itself will be less likely to get nasty surprises.

I cannot begin to count the number of times I've gone to use a library or API method and been stymied as to what it might do when presented with edge cases. Or sometimes even where the edges themselves were.
 
Author
Posts: 13
5
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Tim Holloway wrote:

Junilu Lacar wrote:
Comments that explain why the code is written in a certain way are most helpful.



That happens to be exactly what I argue in the book!

 
Master Rancher
Posts: 4023
53
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
It's important to distinguish between documentation comments, which are effectively part of the API of a class, and implementation comments, which are purely internal.  

Most of the discussion in this thread seems be about documentation comments, which are the ones that begin with /** and form the JavaDoc for your classes.  In those, yes it's important to avoid discussing unnecessary internal details that you may want to change later.  

However, that does not apply at all to implementation comments, which are the ones that begin with /* or //.  Those do not make any commitment to client code in other classes; they are purely to aid in understanding, for anyone reading this code.  These are the ones where often the best thing you can comment on (if you find the need to comment at all) is why you did things the way you did.  Or also, why you didn't use some other approach that might have seemed a good idea.  Perhaps you discovered a problem with an alternate approach, and want to warn a future coder against replacing your code with something else.  That's a great topic for an implementation comment, but probably not for a documentation comment.  Unless part of the warning is meant for clients of your code, in which case yes, put it in a doc comment.
 
Consider Paul's rocket mass heater.
reply
    Bookmark Topic Watch Topic
  • New Topic