Code documentation (Part 1)

Part 1

Writing code is awesome. Have you ever compared coding works to the work of the potter ? He starts with a piece of clay, shapes it , refines it up to the final object. None from its production is fully identical to an other. Same thoughts apply to the coding works: the language is potter’s wheel, the bits, instructions, functions are the clay and the application is a plate, a jug, a vase. And we all know that we have our tricks, our fads, so that none from my code compares exactly to my colleagues.

As far as creativity is concerned, every thing is fine . However, the side effect of this statement relates to the documentation. As my own thoughts change along the time, my coding skills evolved too probably so that I am now confused when I get back to dated code which lacks critical documentation. I can remember very well a pretty tricky coding section that I worked on 8 years ago, that was so trivial to me at this time so that I did not document it exhaustively (apart from the basic standard line commenting). It took me an hour or two to reverse engineering this code up to the ascertainment that this was just a nice trick and not so much rocket science, however tricky enough to require some more comments.

Now that I handle x00.000 lines of code (actually 800 Mb of VB.NET code and 400 Mb of c/c++ code), documentation becomes quite critical. I paid a particular attention to my c/c++ libraries which are the fundamental basis for most of my applications and I decided to put some efforts on documenting my code, and improving the global description of the code in order to ease the use of these libraries and their inclusion in application code.

I searched the net, asked my colleagues about the de facto standard application for documenting c/c++ code and looked at what others did when writing code. In the end, Doxygen appeared to be the application I was looking for. The quite nice thing about Doxygen is its ability to run apart from the code (as long as you pass the proper parameters); most IDE’s feature optional plugins including Doxygen plugins, more or less sophisticated which help a lot in documenting the code, extracting the information and building the documentation files (html, chm and latex actually). The rules are quite easy to understand, quite flexible, and once again, you can write your comments and documentation blocks the way you like.

Here are a few links to Doxygen:

Leave a Reply

You must be logged in to post a comment.