THE NIGHTMARE OF PROGRAMERS: DOCUMENTING SOURCE CODE

Let's face it! There are some tasks that most programers avoid doing and leave them as a "sticky" ToDo entry, and one of them is to document all the software elements in the source code they are working on: classes, structs, properties, operations/methods, etc.

Why can't any programer take the proper time to execute this task? The quick answer: because it's too boring ...

... and please bear in mind that we are leaving out any references to other aspects of the task, like how hard is to find common rules to follow (and learn them by heart) and, of course, writting the proper words or explanation so that any person (including yourself at a later time) can understand what is going on with that particular piece of code.

Well, exactly a week ago Eric ("TehOne") and I exchanged a couple of messages about tools that make your life easier when you want to document source code (by the way, having read the code of his mouse component, one realizes the great benefits of properly commenting source code).

There used to be an open project called "nDoc" (I bet you know it) which never reached a beta stage for v2 (which would support the whole .NET Framework 2, once released the final build).

Unfortunately, the project was abandoned on the alpha stage. But luckily, Microsoft came to the rescue with "Sandcastle": a console application that builds documentation from the xml files that the Visual Studio IDE generates by request (even in the express editions).

"Console application"? Yes, you've read it. And I know what you're thinking: "Why things have to be so complicated?". Well, to answer that let me tell you that there exists some open GUI projects that will ease the task, being -in my honest opinion- one of the most useful and easy-to-use applications: the "SandCastle Help File Builder".

The beauty of it is that it really works and does a great job with any XNA-based programs, but there are some things that you must know though:

• The process verifies any dependencies for the assemblies you want to document, so you have to specify whether you want to include the documents of these dependencies in the final help file or not. In case of the latter, you have to manually add the assemblies to the dependencies' collection in the GUI.
• Sometimes, when you want to open the "Namespaces" form -so as to tell the GUI which namespaces must be documented and which ones must not - you may find that that an exception is thrown by the application and not all the namespace or none are listed. If that is the case, you can edit with the notepad the project file (".shbf"), adding the missing namespaces:

<namespaceSummaries>
<namespaceSummaryItem name="NamespaceRoot.MyNamespace1" isDocumented="true">This is an example.</namespaceSummaryItem>
<namespaceSummaryItem name="NamespaceRoot.MyNamespace2" isDocumented="false" />
...
</namespaceSummaries>

Now, you may say "Ok, but I still have to type the whole comments, explanations and links to all those "see" and "seealso" references (like, say, complete namespaces)" in VS IDE. Right. But there's exist an add-on for Visual Studio that -even though it does not miracles in some cases- makes the task a lot easier: "GhostDoc". I must admit that never used this add-on, but for what I can see and read in this site it seems to be a great tool. However, it does not support express editions ... :(

To sum up, take your time to comment the code, find the method that suits you, but don't leave the task as an "never-ending" ToDo entry; just believe me you won't regret it.

Take my case for instance, it took me two days to properly comment the source code of my Warm-Up Challenge entry! (And yes, I'm still working on it -on my sparetime- even though the challenge is over ... Why? Becuse it helps me learn and implement my-own "best practices" on designing and implementing a game with XNA -either for the main compo or any other compo to come). And by "properly" I mean the way I want to see the comments on the final documentation.

So remember: do as I say, not as I do ... or did, actually ... ;)

BTW, if someone happens to know any program like GhostDoc that works with VS Express editions please drop a comment (and or message to my email address). Ditto for any free application/add-on that helps building Design Class Diagrams of .NET applications.

'till later.