Re: Coding Standards
- From: Lew <lew@xxxxxxxxxxxxx>
- Date: Fri, 31 Aug 2007 10:45:44 -0400
Karl Uppiano wrote:
-- except for JavaDocs, which I write copiously. It gives me a nice place to describe the class, member variable, or method, with the input parameters, return values and exceptions thrown, in a way that is far more structured than you would get with ad-hoc comments.
Matthias Buelow wrote:
Which are exactly the kind of useless comments that clatter source code.
I thought the code should be expressive enough without all that chatter?
Documenting trivial details is nonsense. You should explain the big
picture in comments and why you did some details the way you did them,
and not verbosely reformulate parts of the source code.
While I agree with Matthias's points about commenting the more obscure parts of one's code, I cannot believe that he seriously is against the use of Javadocs. Javadocs are critical in Java source. They serve double duty - not only do they help future users of a class to use it correctly, they cover most of the non-trivial comments one would make about a class or method (or other exposed member). It's hardly "chatter".
--
Lew
.
- Follow-Ups:
- Re: Coding Standards
- From: Matthias Buelow
- Re: Coding Standards
- From: Martin Gregorie
- Re: Coding Standards
- References:
- Coding Standards
- From: davidsamith@xxxxxxxxx
- Re: Coding Standards
- From: Karl Uppiano
- Re: Coding Standards
- From: Matthias Buelow
- Coding Standards
- Prev by Date: Re: How to read and parse a remote XML file with Java
- Next by Date: Is JAAS okay for client apps?
- Previous by thread: Re: Coding Standards
- Next by thread: Re: Coding Standards
- Index(es):
Relevant Pages
|
