Most gratuitous comments

[Grant Edwards]

On 2014-11-21, Marko Rauhamaa <marko at pacujo.net> wrote:
> sohcahtoa82 at gmail.com:
>
>> My point was that I was making fun of CS professors that demand a
>> comment on every line of code, regardless of how clear the line of
>> code is.
>
> Unfortunately, a lot of software houses do a similar thing. Not quite
> every line, but stuff like:
>
>    def write_line_to_file(file, line):
>        """Write a line to a file.
>
>           file is the file to add a line to
>           line is the line to add to the file"""
>        ...

And then they run the whole steaming pile through doxygen to generate
several shelf-feet of utterly useless "documentation" to which than
can proudly point the next time the ISO-900<whatever> inspectors come
around.  A few years later, the previously correct-but-pointless
comments and wheelbarrows full of paper are now incorrect, and instead
of providing zero value they provide _negative_ value.

-- 
Grant Edwards               grant.b.edwards        Yow! ... I'm IMAGINING a
                                  at               sensuous GIRAFFE, CAVORTING
                              gmail.com            in the BACK ROOM of a
                                                   KOSHER DELI --