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.

Gunnar Peipman

Gunnar Peipman is ASP.NET, Azure and SharePoint fan, Estonian Microsoft user group leader, blogger, conference speaker, teacher, and tech maniac. Since 2008 he is Microsoft MVP specialized on ASP.NET.

    2 thoughts on “Documenting source code

    • August 5, 2009 at 4:58 pm
      Permalink

      This blog is well-intented but not highly informative. It would be nice to see examples of a well commented class, interface and properties. Plus, examples would make some things clearer. For example, you said class comments should include: “expected usage of class” and “context in which class is used”. These would make sense if I had examples.

      Additionally, if commenting is so good why don’t all Software Engineers use it. TIME! You ought to explain how your ideas make it worth the extra time which Software Engineers lack.

    • August 15, 2009 at 9:29 am
      Permalink

      Mark:
      I agree to a point but not completely. The method that looks like this

      int foo () {
      // do a

      // do b

      // do c

      }

      is definitely an antipattern, but there are other, good reasons for comments inside a method. Sometimes a method does something in a confusion or non-obvious way, but for a good reason. Some concepts, like the idea that a sequence of statements has strong ordering constraints, are not redily expressable in most programming languages. Sometimes I but comments arround bug fixes — especially if its a bug I’ve made more than once.

      Its easy when you write small demo programs to confidently state that there are hard and fast rules that should never be broken. Real engineering is a process of compromise, and just about every rule gets broken eventually. A well placed comment can ameliorate a lot of the damage from doing so.

    Leave a Reply

    Your email address will not be published. Required fields are marked *