[JSR308] Can we agree on our goals?
eu at javatx.org
Sat Feb 3 12:34:23 EST 2007
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
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.
More information about the JSR308