"Don’t comment bad code - rewrite it." (Brian W Kernighan & Phillip J Plauger, "The Elements of Programming Style", 1974)
"Don't just echo the code with comments make every comment count." (Brian W Kernighan & Phillip J Plauger, "The Elements of Programming Style", 1974)
"Make sure comments and code agree." (Brian W Kernighan & Phillip J Plauger, "The Elements of Programming Style", 1974)
"Notice that even the data is commented. One of the most effective ways to document a program is simply to describe the data layout in detail. If you can specify for each important variable what values it can assume and how it gets changed, you have gone a long way to describing the program. [...] Document your data layouts." (Brian W Kernighan & Phillip J Plauger, "The Elements of Programming Style", 1974)
"The best documentation for a computer program is a clean structure. It also helps if the code is well formatted, with good mnemonic identifiers and labels (if any are needed), and a smattering of enlightening comments. Flowcharts and program descriptions are of secondary importance; the only reliable documentation of a computer program is the code itself. The reason is simple -whenever there are multiple representations of a program, the chance for discrepancy exists. If the code is in error, artistic flowcharts and detailed comments are to no avail. Only by reading the code can the programmer know for sure what the program does." (Brian W Kernighan & Phillip J Plauger, "The Elements of Programming Style", 1974)
"Writing a computer program eventually boils down to writing a sequence of statements in the language at hand. How each of those statements is expressed determines in large measure the intelligibility of the whole; no amount of commenting, formatting, or supplementary documentation can entirely replace well expressed statements. After all, they determine what the program actually does." (Brian W Kernighan & Phillip J Plauger, "The Elements of Programming Style", 1974)
"The most common kind of coding bug, and often considered the least harmful, are documentation bugs (i.e., erroneous comments). Although many documentation bugs are simple spelling errors or the result of poor writing, many are actual errors - that is, misleading or erroneous comments. We can no longer afford to discount such bugs, because their consequences are as great as 'true' coding errors. Today programming labor is dominated by maintenance. This will increase as software becomes even longer-lived. Documentation bugs lead to incorrect maintenance actions and therefore cause the insertion of other bugs." (Boris Beizer, "Software Testing Techniques", 1990)
"Any comment that forces you to look in another module for the meaning of that comment has failed to communicate to you and is not worth the bits it consumes." (Robert C Martin, "Clean Code: A Handbook of Agile Software Craftsmanship", 2008)
"Obsolete comments are worse than no comments." (Douglas Crockford, "JavaScript: The Good Parts", 2008)
"Comments are not evil. They are as necessary to programming as basic branching or looping constructs. […] On the other hand, you can go too far in your commenting. Make sure that your comments clarify your code but do not obscure it. Sprinkle your code with relevant comments explaining what the code is supposed to accomplish. Your header comments should give any programmer enough information to use your code without having to read it, while your inline comments should assist the next developer in fixing or extending it." (Cal Evans [in Kevlin Henney’s "97 Things Every Programmer Should Know", 2010])
"Comments that parrot the code offer nothing extra to the reader - stating something once in code and again in natural language does not make it any truer or more real. Commented-out code is not executable code, so it has no useful effect for either reader or runtime. It also becomes stale very quickly. […] A prevalence of noisy comments and incorrect comments in a codebase encourages programmers to ignore all comments, either by skipping past them or by taking active measures to hide them. Programmers are resourceful and will route around anything perceived to be damage: folding comments up; switching coloring scheme so that comments and the background are the same color; scripting to filter out comments." (Kevlin Henney, [in Kevlin Henney’s "97 Things Every Programmer Should Know", 2010])
No comments:
Post a Comment