[JSR308] Can we agree on our goals?

[Ted Neward]

The comment that ...

"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 Neward
Java, .NET, XML Services
Consulting, Teaching, Speaking, Writing
http://www.tedneward.com
 

> -----Original Message-----
> From: jsr308-bounces at lists.csail.mit.edu [mailto:jsr308-
> bounces at lists.csail.mit.edu] On Behalf Of Eugene Kuleshov
> Sent: Friday, February 02, 2007 6:55 PM
> To: jsr308 at lists.csail.mit.edu
> Subject: Re: [JSR308] Can we agree on our goals?
> 
> Hani Suleiman wrote:
> >>  By the way, Hani, you have voted yes for the JSR 308. Have you
> >> changed your mind since then?
> > Of course not! Being concerned is *healthy*, throwing ones hands up
> > and giving up (so early in the game too) is not. Specifically:
> >
> > - Pushing the problem of readability on tooling is not a good
> > solution. Sure, IDE's might help, but source files are plaintext ,and
> > should be editable and easy to understand as such. So any syntax
> > constructs we come up with should take that into consideration. A
> > source file that is mostly annotations where the actual code is hard
> > to find is a bad thing for Java. Surely we can all agree on that?
>   I can't agree with that.
> 
>   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. On the other hand, those comments does not help
> tools to read very same code (unless those tools are using artificial
> comment structurization, like we have seen in XDoclet or JML).
> 
>   Also, it is been mentioned in the discussion, those new annotations
> won't appear in every source file. They COULD appear in some code and it
> is up to the developers to use their common sense and the best practices
> to apply these annotations where it is appropriate. But it is also
> understood that language designer can't count on the language user
> common sense.
> > - Based on the above, restricting where annotations can be places is
> > worth discussing (as we are). I'm on the fence right now with regards
> > to allowing it on code blocks. I can see the benefits, but worry about
> > the clutter. It's even debatable whether it should be allowed on
> > loops, given that forcing a block onto a loop to annotate it seems
> > somewhat awkward.
>   I find it at least strange from the language point of view to allow
> annotations only on and not on all constructs that allows blocks. Can we
> all agree that is should be either all blocks or none and focus further
> discussion on how we can address raised issues and/or keep code readable?
> 
>   regards,
>   Eugene
> 
> 
> 
> _______________________________________________
> JSR308 mailing list
> JSR308 at lists.csail.mit.edu
> https://lists.csail.mit.edu/mailman/listinfo/jsr308
> 
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.5.432 / Virus Database: 268.17.19/663 - Release Date: 2/1/2007
> 2:28 PM
> 

-- 
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.5.432 / Virus Database: 268.17.19/663 - Release Date: 2/1/2007
2:28 PM