Someone once said we should prefix all our methods with the /// <summary> comment blocks (C#) but did not explain why.
I started to use them and found they annoyed me quite a bit, so stopped using them except for libraries and static methods. They're bulky and I'm always forgetting to update them.
Is there any good reason to use /// <summary> comment blocks in your code?
I normally use // comments all the time, it's just the /// <summary> blocks I was wondering about.
Use them as much as possible.
Yes, those are special comments that become the documentation for the method. The contents of <summary>, the parameter tags, etc. that are generated show up in intellisense when you or someone else is getting ready to call your method. They can essentially see all the documentation for your method or class without having to go to the file itself to figure out what it does (or try to just read the method signature and hope for the best).
Yes, absolutely use them for anything you want to keep, or might be shared.
Also, use them in conjunction with Sandcastle and the Sandcastle Help File Builder, which takes the XML output and turns it into beautiful, MSDN-style documentation.
Last place I worked we re-built the documentation every night and hosted it as an internal homepage. The company initials were MF, so it was MFDN ;)
Normally though I just produce a .chm file, which is easily shared around.
You'd be surprised how addicted you get to documenting everything once you start seeing it in MSDN format!
If your coding standard demands that you use such comments (and a coding standard for an API or a framework may demand that), then you have no choice, you have to use such comments.
Otherwise, consider seriously not using such comments. You can avoid them in most cases by changing your code like this:
/// <summary>
/// Checks if a user is authorized to access the resource
/// </summary>
public bool SecurityCheck( User user ) {
}
to
/// <summary>
/// Checks if a user is authorized to access the resource
/// </summary>
public bool IsAuthorizedToAccessResource( User user ) {
}
to
public bool IsAuthorizedToAccessResource( User user ) {
}
Your class, method, & property naming should be self evident, so if you need these, it's probably a smell.
However, I would recommend using them on any public classes, methods, & properties in an API, library, etc... At the very least, they will generate the docs to help any dev using your it, and will prevent you from having to write them.
But anyway you slice it, maintain them or delete them.
Forgetting to do something doesn't make it a bad idea. Forgetting to update any documentation is. I've found these very useful in my programming and people that inherit my code are thankful to have them.
It is one of the most visible ways to document your code.
It is a pain to have to find the source code to read inline documentation or dig up a document that goes over what code does. If you can have something useful pop up through intelligence then people will love you.
If you find that you have to keep going back and editing your comments to correspond with new code, you might be doing them wrong in the first place. The summary element should contain exactly that - a summary - the what and the why of the thing your'e summarising.
Describing how something works in comments violates DRY. If your code is not self-descriptive enough, maybe you should go back and refactor.
Yes, I've created them. [when building new systems from scratch]
No, I've never benefited from them. [when working on existing systems that needed maintenance]
I've found that "Summary" comments eventually tend to get out of sync with code. And once I notice a few badly behaving comments, I tend to lose faith in all comments on that project - you're never sure which ones to trust.
"It has to be Used Very much, like me ;)"
I used to play with comments (///). For a class you can simply do a comment like this
namespace test
{
/// <summary>
/// Summary description for Calendar.
/// </summary>
public partial class DatePicker : System.Web.UI.Page
{
But, for a method you can add-on more with giving description for parameters and return types.
/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{
You can use a short-cut for creating this comment (///+Tab).
using them except for libraries
That's the time they are useful. With XML Documentation generation turned on and a reference to the assembly, without its project, will show more detail in intellisense.
But for the internals of the current project, they just get in the way.
I use them, but as some other people have said not universally. For small methods they can easily be larger than the code they're explaining. They are most useful for generating documentation that can be given to people new to the system so that they have something to refer to while learning it. Even though, as programmers, we can usually ferret out what some code is for it is nice to have the comments to guide us and act as a crutch. If it has to be written down somewhere then in the code is the place it is most likely to stay updated (more likely than some Word document floating around).
I use the equivalent in VB (since they won't let me use C# - apparently it's too hard... no comment.) I find them very convenient. Most of the time I wait until the procedure or function is pretty much completed before putting them in, if only to avoid having to change the comments - or have them "out of sync".
I don't necessarily write a novel - just the basics, the parameter description and some remarks (usually when there's something "out of the ordinary" going on in there - workaround or other crap that I'd rather not have in there but have no choice "for now".) (Yeah, I know, that "for now" can last years.)
I'm severely irritated by uncommented code. A consultant wrote the initial version of one of our components and didn't comment anything and his choice of names leave to be desired here and there. He's been gone over a year and we're still sorting out his stuff (in addition to working on our own stuff.)
