[JSR308] Can we agree on our goals?

[Ted Neward]

>   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".
> 
Well, certainly my anecdotal experience from conference attendees and class
participants would suggest that this percentage is larger than you're making
it seem. Agile is having a pretty large impact on the developer community as
a whole, and even if a team doesn't pronounce themselves as "agile", they're
adopting a lot of agile practices.

>   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.
>
But we're losing sight of the main point, which was, once again, code
clarity and readability. We do not want to enable annotations on various
language constructs simply because we "can", but because the gain in power
and expression will offset the added linguistic complexity.

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: Saturday, February 03, 2007 9:34 AM
> To: jsr308 at lists.csail.mit.edu
> Subject: Re: [JSR308] Can we agree on our goals?
> 
> 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
> 
> 
> 
> _______________________________________________
> 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