SV: SV: Regarding coding style

K Viltersten tmp1 at viltersten.com
Sun Mar 9 00:14:03 CET 2008


> 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++), there
won't be any source code, except for 
method declarations. 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);

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

I don't see how this is dislikeable. Please 
explain. Perhaps the above IS what you 
ment by "docstrings"? 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.   ;)

--
Regards
Konrad Viltersten
--------------------------------
sleep    - a substitute for coffee for the poor
ambition - lack of sense to be lazy




More information about the Python-list mailing list