First Aid Kit

 < Day Day Up > 



Most of the tools for documentation center on either self-documentation of code or the extraction of documentation from the code and comments automatically. Let us look at each of these types of tools separately.

Self-documentation is possible without any extra tools to some degree in all programming languages; simply choose the best names from code elements. Nevertheless, some programming languages have extensive support for creating self-documenting code.

One language feature that is geared directly toward self-documenting code is Design by Contract programming. This is an integral part of the Eiffel programming language. The idea is to provide a visible contract that a function must fulfill. This ensures that both the user of the function and the writer of the function understand the necessary preconditions, post-conditions, and invariants that the function must obey. Because this is part of the language, it is enforced by the compiler and is not prone to the same synchronization problems that plague code comments. Other languages have similar extensions, such as iContract for Java, but portability is reduced because it is not an inherent part of the language.

It is also possible to create your own domain-specific language that uses terminology directly from the target domain. While this is appealing, a considerable amount of work is involved. Loss of portability and a high learning curve can also be deterrents, although the learning curve is reduced if the language is well designed and the programmers must learn the language of the target domain anyway. Nevertheless, if you decide to pursue this course, the most commonly used tools are lex and yacc, which can be used to create custom compilers and interpreters from a standard language specification. See [Levine92] for more detail.

Automated documentation systems come in a couple of varieties. Several freely available systems, such as JavaDoc and Doxygen (Figure 6.2), require a particular format to the comments that they parse. As long as this is begun at the beginning of the project, this is an excellent method for providing appropriate comments as well as automatic generation of separate documentation. Some editors, such as IntelliJ’s IDEA, are also able to use these for providing tips and information while editing (Figure 6.3).

click to expand
Figure 6.2: Configuration dialog for Doxygen, an automated documentation generator. Notice that several different output formats can be seen in the tabs, such as HTML, LaTeX, RTF, and man pages.

click to expand
Figure 6.3: A tool-tip appears in IntelliJ’s IDEA to show the JavaDoc comments for a member function.

The second type of automated documentation is useful if you have a legacy system or one later in development that does not follow any documentation standards. Applications such as Doc-O-Matic from toolsfactory are able to extract reasonably accurate approximations from existing comments based on various heuristics.

Another tool that is very useful for improving automated documentation is documentation validation, such as iDoc for Java. These tools check to ensure that the comments match the code at a syntactic level, catching some of the more common oversights caused when code is changed but the comments are not updated. Documentation validation should be integrated with the build process for documentation to ensure that the latest documentation accurately reflects the way the code works. Some editors, such as IntelliJ’s IDEA, might also provide this functionality while you edit, making it even easier to catch these oversights.



 < 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