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++), 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.
The problem is that tools like Doxygen and JavaDocs generate warnings and errors and things if everything isn't documented "completely". So you end up with a lot of silly boilerplate. I see this kind of nonsense a lot: /** * Get the width of a box * * @param box the box * @returns its width */ extern int box_get_width(box box); You are right that is it often useful to document what to pass to a method and what to expect back and that if this is done well in many cases it isn't necessary to see the implementation. But in many other cases it's obvious, and in other cases it's obvious if you just look at the source which you've got. What's needed is just a bit of common sense and pragmatism: APIs need more documentation if the source of the implementation isn't being released with them, and some APIs just need more documentation than others anyway. Python docstrings, like most things in Python, demonstrate this kind of common sense: you write what you want in them and as far as I can tell nothing complains if you don't write them at all. The lack of fascism is the big innovation. It sounds simple but it makes a huge difference: it's much easier to find (and keep up to date) the real documentation if it's not hidden in a forest of bogus documentation. -- http://mail.python.org/mailman/listinfo/python-list
