Articles‎ > ‎

Documentation How-To

posted Jan 29, 2011, 2:38 AM by Michael Schollmeyer

How to Write Good Documentations

A crucial aspect of a well written class is its documentation. A good documentation boosts reuse fo your class because you and others will find it more useful, maintenance and extensions are easier to do and you will have less bugs at the end. 

A real time saver but why do people have such a hard time writing good class documentations? 

Well, at first I think doumentation is usually done after implementation and this is the first mistake. It is hard to convince someone who thinks he is done to place some more effort onto a task. What are the components of a good documentation? Here are the key points: 

Summary

A class documentation begins with a one sentence summary. Most documentation tools use this summary alongside the class in overview tables, so it should really be compact. 

If you can't find the sentence go back to design. It is not a good idea to implement something you cannot explain. 

Inteded Usage

Write a code snippet that shows how to use the class. Documenting a class from the client perspective also ensures that if can easily be used. Some design flaws can be spotted faster from the client perspective. 

Layer

On which layer is your class located. Is it technical or business code? 

Restrictions

Tell the user under which conditions he can expect the class to behave as expected. 

Limitations

Tell the user that the class can <em>not</em> do. This is just as important as telling the user what it can do. 

Side Effects

If you have them, tell the user. 

Multithreading

Tell the user if the implementation is thread-safe or not. 

Build and Verify

When you are set, run your documentation tool and review your documentation in the tool's output. This will give you a much better impression than reading in the source code. It will also show you broken links and inappropriate formatting.
Comments