| < Day Day Up > |
|
The symptoms of Docuphobia are:
A total lack of comments located anywhere in the code is the most obvious.
Header comments that do not explain what the code does and, when necessary, how it does it.
Comments in the source code that are only repeating what is already apparent from the source code, instead of why it is being done.
Source code called incorrectly by other programmers.
To prevent Docuphobia:
Find a balance that provides enough comments to make understandable code without becoming a tedious chore that does not add extra meaning.
Write self-documenting code.
Write documentation in the comments of the code rather than in some external source.
Make documentation a part of the coding standards.
Avoid information duplication in documentation as much as possible just as you would in code.
Automate the generation of external documentation from the comment documentation.
Ensure that the documentation is easy to maintain and update.
Check documentation validity as part of the build process.
To cure the effects of Docuphobia:
Analyze the current documentation, looking for missing or incorrect documentation.
Determine what the proper documentation is based on the code and questions to the original code writer if possible.
Ensure that you fully understand what the code is doing before documenting it, or request that someone who already knows the code document it.
Add missing documentation as part of the learning process that is inherent in refactoring.
Update documentation as you refactor.
| < Day Day Up > |
|