Summary

 < 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 > 



Preventative Programming Techniques. Avoid and Correct Common Mistakes
Preventative Programming Techniques: Avoid and Correct Common Mistakes (Charles River Media Programming)
ISBN: 1584502576
EAN: 2147483647
Year: 2002
Pages: 121
Authors: Brian Hawkins

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net