Commenting Source Code in .NET

In any project involving more than two developers you have to document the source code. All developers give an extreme laziness when it comes time to put into words the result of several hours, days or weeks of hard work.

But you have to get used to review the code to comment on everything thoroughly, so the next developer who must maintain or modify the code can understand perfectly without making debug the code. Believe me, he will be eternally grateful.

Another key aspect is to comment the classes, methods, attributes, etc, so that with a brief explanation about inputs, otuputs and what it do. This will allow our code is really a black box to the other developers on our team, and are certain they are using the proper method to get the result we want.
 
With .NET we don't have excuse for not doing so, as this administration is almost automatic. The steps are:

1 - Commenting members

Any language. NET has the option to generate documentation through comments with 3 slash (///) within the source code. Pressing key 3 times "/" over any member (class, method, attribute, etc) automatically. NET generates a code where you can enter data related to the member concerned.

 

All these comments will then be displayed on the Intelligence of Visual Studio when we access to the members.

2 - Generate documentation

 These comments are automatically stored in an XML file defined. Later we can generate documentation. The syntax is:

csc yourClass.cs /doc:yourDocumentation.xml 

This means you take all comments and stored in the XML file (for example "tuDocumentacion.xml").

Now, if we work with Visual Studio, we can say that when you build or compile, build your XML file automatically.

This is in Project Properties (Project no solution) -> Generate -> then you should select the box that says "XML documentation file" (note: you must put both Debug to Release).

There is also an Add-On for Visual Studio 2003, 2005 and 2008 called GhostDoc. This Add-On helps us to create the comments, only positioned on the member that want to generate your documentation and pressing the right, and selecting "Document this".

 

3 - Formatting the documentation

Once created our documentation, we provide a format for display.

There are several possibilities:

• Look like msdn, which is Web-like (eg array).
• Look like chm, which is the typical Windows Help

To do this you must download SandCastle which will generate msdn documentation, however, if you want to help generate files like windows style, or the CHM, you must also download HTML Help Workshop.

The only problem is that as Sandcastle has no graphical interface and the process is quite long, the creation of documentation is a bit complicated ... but peaceful there is(are) IDE (s) that abstract complexity. One of them is called SandCastleGUI. (I have test it and really is very easy).

I don't know in other languages as will be commenting source code. Is it as easy?

No more 'copy & paste' in our developments

Once, someone should tell any developer of any project that every time you copy and paste code, God kills a kitten.

The anti-pattern copy and paste programming is an evil that appears often in many projects. The problems stem from this anti-pattern are very numerous, mostly related to the maintainability of code. How often propagates an error code that is not detected, and when it does, it is impossible to solve it in places where we have used the copy-paste.

Basically, copy & paste programming is a full-scale violation a core principle in software development, the first DRY (Do not repeat yourself). Duplication in code often leads to inconsistencies and are a clear indicator that the code is not properly refactoring.

While it is true that every experienced developer knows that eventually the copy-paste is bad, it is also true that it is something we all have done on occasion and that many inexperienced developers often abuse the copy-paste. The problem is that when this abuse is detected the evil already done. Just a little displicinado developer or inexperienced to fall into this error so that the project will suffer the problems associated with it.

Aware of this problem was born Clone Detective for Visual Studio, a fully integrated addin in Visual Studio whose mission is to identify where duplication is being introduced in the code or by copy-paste or by errors in design that force to introduce similar code . Currently only works for C #.

If you want to see how it works before trying to install please visit the video section of the website of the project on Codeplex. A very useful tool.