I’ve seen students in upper-division computer science classes add a comment to each closed brace to indicate what block is ending: if (x > 3) Many junior programmers write too many comments because they were trained to do so by their introductory instructors. Rule 1: Comments should not duplicate the code The rest of this article explains each of these rules, providing examples and explaining how and when to apply them. Rule 9: Use comments to mark incomplete implementations. Rule 7: Include links to external references where they will be most helpful. Rule 6: Provide links to the original source of copied code. Rule 5: Explain unidiomatic code in comments. Rule 4: Comments should dispel confusion, not cause it. Rule 3: If you can’t write a clear comment, there may be a problem with the code. Rule 2: Good comments do not excuse unclear code.
Rule 1: Comments should not duplicate the code. Here are some rules to help you achieve a happy medium: While all of these points are true, it would be a mistake to go to the other extreme and never write comments.
You are, on the other hand, guaranteed that the computer is doing exactly what your code is telling it to.Your compiler doesn’t check your comments so there is no way to determine that comments are correct.Writing and then maintaining comments is an expense.A bad comment is worse than no comment at all. While it’s easy to measure the quantity of comments in a program, it’s hard to measure the quality, and the two are not necessarily correlated. While there are many resources to help programmers write better code-such as books and static analyzers-there are few for writing better comments.
We find some programs harder to understand than others, and we look to comments to help us make sense of them. Compilers and interpreters ignore comments and find all syntactically correct programs equally easy to understand. Famed MIT professor Hal Abelson said: “Programs must be written for people to read and only incidentally for machines to execute.” While he may have purposely understated the importance of running code, he is spot on that programs have two very different audiences.
0 kommentar(er)
