[Rod Johnson] 要写代码注释


Remember that documentation should serve to:

Provide a contract for objects and methods. Test cases for an object are also valuable specifications, and documentation and test cases should be kept synchronized.

Save developers the trouble of needing to read code before they use it. There should be no need to examine a class’s code to establish what it does or whether it works. Javadoc exists to establish what it does, and unit tests should establish that it works as documented.

Explain non-obvious features of the implementation. Deciding what is obvious is a tricky issue. Assume that your readers are competent Java and J2EE developers (unless you know otherwise, for example if you are writing a demonstration application for a new deployment).

Leave a Comment

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.