SV: SV: Regarding coding style

[Grant Edwards]

On 2008-03-08, K Viltersten <tmp1 at viltersten.com> wrote:
>> If you can't/don't look at the source file, 
>> then comments aren't going to help (except 
>> in the case of something like docstrings in 
>> Python).
>
> I strongly disagree. Now, perhaps we're 
> talking about different things, here?
> Usually, in the header file (C++),

Header files are source code.

> there won't be any source code, except for method
> declarations.

Declarations are source code.

> A common example:
>
> /** Projects an object from 3D to 2D using
>     the method of Alexander The Great.
>     \param 3D structure to be projected
>     \returns 2D projection
> */
> public Proj2D get2Dfrom3D(Proj3D param);

That's source code.

> The above is, to me, very clear and 
> consistent. Not to mention, easily 
> handled with e.g. Doxygen to create a
> readable documentation.

I've no problem with that.

> I don't see how this is dislikeable. Please 
> explain. Perhaps the above IS what you 
> ment by "docstrings"?

http://en.wikipedia.org/wiki/Docstring
http://epydoc.sourceforge.net/docstrings.html

> For Java, one has the JavaDocs, a great tool, provided one
> will comment each method and variable used.
>
>>> Now, i'm getting the signal that it's done 
>> in a different way in Python.
>> 
>> I'm not sure how you concluded that from this thread.  
>
> The below, more or less.   :)
>
>> "What I really can't stand are the
>> pointy-haired comment blocks at the
>> beginnings of C/C++ functions that do
>> things like tell you the name and return
>> type of the function and list the names
>> and types of the parameters."
>
> Please note that i DO NOT argue against one
> way or another. I simply expressed surprise
> since i've been tought otherwise earlier
> and, maybe, there's a larger picture than
> what i've seen this far. As stated before, 
> snakeology is a very new area to me. Yet.   ;)

Duplicating information in a comment that is plainly obvious 5
lines below it in the actual source code is a waste of time
when the code is written.  A week later, the comment will be
out of sync with the code and anybody paying attention to the
comment will be mislead.  I exaggerate (slightly), but in my
experience anytime information is duplicated in multiple places
it doesn't take very long at all before it's out-of-sync and
incorrect in all places except one.

-- 
Grant Edwards                   grante             Yow!  I'm using my X-RAY
                                  at               VISION to obtain a rare
                               visi.com            glimpse of the INNER
                                                   WORKINGS of this POTATO!!