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