On 2008-03-08, K Viltersten <[EMAIL PROTECTED]> 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
--
http://mail.python.org/mailman/listinfo/python-list
