>>> 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. > /** > * Get the width of a box > * > * @param box the box > * @returns its width > */ > extern int box_get_width(box box);
Oh, yes. This is stupid. I agree with you. If one's supposed to comment, let him comment RIGHT. Otherwise, let it be. Usually, when i comment my code, it's a blessing. If not, i don't comment at all. > 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. I agree. Sometimes, there's a demand from the customer to comment all methods. Then, and then only, i'll go commenting all. But i believe strongly that we think alike on this one. When it's suitable, it should be there. Otherwise - why bother. Right? > 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. I couldn't agree with you more on this one! Thank you for an interesting discussion. -- Regards Konrad Viltersten -------------------------------- sleep - a substitute for coffee for the poor ambition - lack of sense to be lazy -- http://mail.python.org/mailman/listinfo/python-list
