SV: Regarding coding style

[Grant Edwards]

On 2008-03-08, K Viltersten <tmp1 at viltersten.com> wrote:

>> 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. Gee, thanks.  I never could
>> have figured that out from looking at the source code itself.
>
> Coming from C++/Java camp i can't help noticing that in most
> cases, when i'm using a class written by somebody else, i
> don't want to see his/her code. I only want to know WHAT the
> function does (is intended to be doing, at least).

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 don't want to look at the source code (in some cases i can't
> even see the code because it's compiled). I only care that
> when i execute
>
>   SomeType obj = SomeType();
>   obj.aggregate();
>
> the object gets aggregated. How it's done will be up to the
> author. I'm just a user of the product.

If you don't look at the source file, then I guess the question
of whether comments are good, bad, or indifferent is irrelevent
to you.

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

I very rarely look at the source files for the standard
library. I usually just look at the library reference document.
The only times I look at the source code are the rare occasion
that the function doesn't seem to be working correctly or when
I can't understand what the reference docs are saying.  The
cases where I suspect the former generally turn out to be the
latter.

Comments in source code are for people maintaining the code,
not for people using a standard library API (again, except for
docstrings).

-- 
Grant Edwards                   grante             Yow! YOU PICKED KARL
                                  at               MALDEN'S NOSE!!
                               visi.com