Re: Coding Standards

Karl Uppiano wrote:

For example, my code tends to be completely devoid of comments (because I
find them distracting interspersed with the code -- the code itself should
be expressive enough without all that chatter)

Then you apparently have never implemented any more complicated or
non-intuitive algorithm...

-- 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.

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.

Unfortunately, your approach is typical for many Java (or industrial,
for that matter) programmers.

I've seen quite some programs where the programmer said "don't have to
explain the stuff, the source code is obvious", which were basically
unmaintainable.
.

Relevant Pages

  • Re: GNU Public Licences Revisited (again)
    ... The source code isn't what most programmers are paid for, ... >> secrets' that allow companies to protect their ... Find 100 artists, get 100 ...
    (comp.programming)
  • Re: GNU Public Licences Revisited (again)
    ... In programming source code is the product the ... > The source code isn't what most programmers are paid for, ... >>> secrets' that allow companies to protect their ... Find 100 artists, get 100 ...
    (comp.programming)
  • Re: OT:and long. regards evoting 14th amendment and my hubris
    ... machines with these idiotic electronic ones and the companies are buying the ... stolen...already lost election. ... at this point some very accomplished computer programmers have found ... the first step is writing the "human language" source code. ...
    (alt.support.mult-sclerosis)
  • Re: OT:and long. regards evoting 14th amendment and my hubris
    ... stolen...already lost election. ... at this point some very accomplished computer programmers have found ... the first step is writing the "human language" source code. ...
    (alt.support.mult-sclerosis)
  • OT:and long. regards evoting 14th amendment and my hubris
    ... stolen...already lost election. ... at this point some very accomplished computer programmers have found ... the first step is writing the "human language" source code. ...
    (alt.support.mult-sclerosis)