P Chase wrote: > I think comments within code are often a waste of time, at least > in high level languages.
I agree that trivial comments like those in your examples that directly echo the code are a waste of time, but I wholeheartedly disagree that comments in general are a waste of time. > The code expresses the ideas logically > and unambiguously, which is much harder to do in a natural > language. If the functions and variables are given sensible > names, their meaning is usually clear enough. Clarity is subjective. Function and variable names that are clear to one person, may be obscure in the eyes of another person. We know from other venues that a topic is better understood if different explanations of the topic is provided. In my experience this also applies to source code. One useful type of comments are summaries of what a function does. A parallel is found in technical papers and books which usually start each chapter with a summary of what you can read in that chapter. Another useful type of comments are explanations of why a function works as it does, rather than how something works. Your iteration example is an example of a how-explanation. # For each element in the list, remove leading whitespaces An example of a why-explanation could be # Each element must have leading whitespaces removed because # the subsequent parsing becomes much simpler > (Writing comments > or documentation outside of a program could be useful, however, > for example in giving instructions about how to use a class.) As much documentation as possible should be written within the program to reduce the possibility of the code and the documentation getting out of sync. Such information should be extractable to external documents by use of JavaDoc or similar. > Whenever I've had to understand someone else's code, the first > thing I do is delete all the comments because they are usually > just clutter. For example, I've seen the following: What about the people that comes after you? Are they supposed to infer from the code, what you have learned from the comments? > Where I work now no one writes comments, probably because > the managers are programmers so they know it's a waste of > time. Having worked on several projects where the original developers thought that comments were a waste of time, I can assure you that they are not. - Automatic footer for [EMAIL PROTECTED] ---------------------------------- To unsubscribe from this list, mail [EMAIL PROTECTED] unsubscribe discuss To join the announcements list, mail [EMAIL PROTECTED] subscribe announce To receive a help file, mail [EMAIL PROTECTED] help This list is archived at http://www.mail-archive.com/discuss%40ppig.org/ If you have any problems or questions, please mail [EMAIL PROTECTED]
