Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!nntp.club.cc.cmu.edu!micro-heart-of-gold.mit.edu!bloom-beacon.mit.edu!bloom-beacon.mit.edu!panix!not-for-mail
From: Grant Edwards <invalid@invalid.invalid>
Newsgroups: comp.lang.python
Subject: Re: Most gratuitous comments
Date: Fri, 21 Nov 2014 17:04:24 +0000 (UTC)
Organization: PANIX Public Access Internet and UNIX, NYC
Lines: 29
Message-ID: <m4nrao$6b8$1@reader1.panix.com>
References: <546d7505$0$12899$c3e8da3$5496439d@news.astraweb.com> <b7dff0ad-9654-416b-9e99-6341aff2b872@googlegroups.com> <b932kb-isj.ln1@chris.zbmc.eu> <25fa214f-2060-46a8-bebf-d191d69e9a9c@googlegroups.com> <546e7644$0$13014$c3e8da3$5496439d@news.astraweb.com> <6ab51e97-19c5-4008-a755-c55eb71469ba@googlegroups.com> <87fvdd6o5c.fsf@elektro.pacujo.net>
NNTP-Posting-Host: 67-130-15-94.dia.static.qwest.net
X-Trace: reader1.panix.com 1416589464 6504 67.130.15.94 (21 Nov 2014 17:04:24 GMT)
X-Complaints-To: abuse@panix.com
NNTP-Posting-Date: Fri, 21 Nov 2014 17:04:24 +0000 (UTC)
User-Agent: slrn/1.0.1 (Linux)
Xref: csiph.com comp.lang.python:81228

On 2014-11-21, Marko Rauhamaa <marko@pacujo.net> wrote:
> sohcahtoa82@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 --