Documenting source code

Source code documenting is very important task. Code documentation servers as persisted communication between developers who are using same code. Undocumented or poorly documented code may be hard to understand to other developers who have then waste their valuable time to struggling through the code they don’t understand well. In this posting I introduce you some code documenting tips.

Note. I describe here code documentation you can produce using Visual Studio IDE. I don’t cover here documentations written for print media on word processors.

Worst practices

I have some awful experiences on working with undocumented and poorly documented code. When some library starts throwing unknown exceptions and all information you get is that Controller<SomeUnknownType>.KinkyMethod<SomeOtherType>() did something unexpected you are in trouble.

Here is one reality-show example.

/// <summary>
/// Shows the messages.
/// </summary>
/// <param name="messages">The messages.</param>
public void ShowMessages(string[] messages) 
{
    // Do something
}

You need some documentation to find out what different points in code flow do and how they act. If you don’t have documentation or you have documentation that sais almost nothing useful you have to invest your time to discover what goes wrong and why. I think we all know how time consuming these problems are.

Documentation basics

Documentation, what ever it is about, must be short and clear. If somebody else reads it he or she must be able to understand quickly what documented item exactly does and what behavior to expect. If class is written by you then you know exactly how it works and why it works this way. Other developers may not have this knowledge and they may not find your class name and method names intuitive.

Of course, one may argue that ideal code is self-describing etc. The problem is simple – we are not living in ideal world. So our code is never ideal and we are never ideal. Even if two people agree on something they usually don’t understand things exactly same way.

Interface documentation should describe:

• purpose of interface,
• expected usage of interface.

Class documentation should describe:

• purpose of class,
• expected usage of class,
• context in which class is used,
• implementation details for developers who extend the class.

Method/property documentation should describe:

• what method/property does,
• what method of property returns,
• parameters of method,
• are there both getter and setter for property,
• exceptions that method/property directly throws.

My list is not long but it gives you some idea about what code documentation should contain. You may always find people who argue that code documentation is not needed. I don’t believe them. Don’t forget one thing – when you work on your old code again after three months or year then you get one new role: you are also client of your code because you don’t remember all the details anymore.