[JSR308] Can we agree on our goals?

[Eugene Kuleshov]

Ted Neward wrote:
> "Currently it is quite possible (and in fact, many developers do that) to
> document code using huge comments, including class and method javadocs, as
> well as block and line comments even inside method body. Does it make code
> hard to find? Probably yes. Does it help user to read the code? Probably
> yes. Strangely, no one think that those comments do clutter source code."
>
> ... quite honestly, is not true! People DO think that those comments clutter
> source code. In fact, the agilists among us would have you write *fewer*
> comments, in order to help make the code more clearly understood (more
> self-documenting, as it were), and therefore, unnecessary to comment!
> (Martin Fowler, "Refactoring") And it's been well-documented for years that
> "comment entropy" sets in very quickly without an aggressive policy of
> keeping comments in sync with changing code, so programmers are, in fact,
> becoming leery of "too much" commenting.
>   
  Ted, do agree with you that it is better practice to write less 
comments. Unfortunately it is still less then common practice and 
unfortunately we can't say that "agilist" fraction represent big part of 
"many developers".

  Anyways, as you pointed out, there is a movement to write less 
comments because they are getting out of sync. That would also help 
tools like JML, that are heavily comment based, only because they have 
no other choice at the moment. So, tools like that would benefit from 
the structurized information semantically linked to the code.

  regards,
  Eugene