Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Someone once said we should prefix all our methods with the /// <summary> comment blocks (C#) and I am wondering if that is true or not.

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. Do you recommend using them? Why?

EDIT: I normally use // comments all the time, it's just the /// <summary> blocks I was wondering about

share|improve this question
2  
Isn't this a programming question that belongs on Stack Overflow? –  Jim Puls Sep 21 '10 at 17:19
1  
I wasn't sure if these comment blocks were personal preference or recommended standards –  Rachel Sep 21 '10 at 17:40
1  
I think SO as well. –  Ryan Hayes Sep 21 '10 at 20:43
24  
I think this is exactly the kind of question that belongs here. There's a good chance that this would be closed on stackoverflow as being subjective. –  Paddyslacker Sep 22 '10 at 20:30
    
Use <summary> blocks if you want to generate documentation. This would make sense if you are making an API for others to use. Doing this for every method is overkill and decreases your flexibility. –  Macneil Mar 9 '11 at 5:16
add comment

14 Answers

up vote 78 down vote accepted

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).

share|improve this answer
19  
+1 Absolutely use them. You would be surprised at how useful it is to have them if you ever reuse your components and have all that great documentation available in intellisense. –  Walter Sep 21 '10 at 14:43
4  
Also if you're using Visual Studio and begin a line with /// just before a class, method or field declaration, VS will generate the XML documentation structure for you - you just have to fill it in. I agree that it takes up a lot of space of your screen, but it's a worthy compromise I'd say. Also, F# has some better support for it (e.g. you don't have to use <summary> and </summary> since they are 'assumed'). –  ShdNx Sep 21 '10 at 17:08
7  
Because this answer is already the best choice I will just add my comment: When I found out that the summary is used for intellisense, and my projects grew to their current size, I was very glad to have found this feature. Remembering what my methods and classes are for was becoming a huge challenge, and documenting code via this mechanism greatly simplified things, allowing me to focus on new code and resusability instead of trying to remember what was done months ago. –  JYelton Sep 21 '10 at 17:19
1  
Just one thing to add, these comments aren't compiled into the dll, you have to deliver the associated xml file with your dll. –  Benjol Mar 9 '11 at 5:44
add comment

Yes, absolutly 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.

alt text

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!

share|improve this answer
add comment

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 ) {

    }
share|improve this answer
8  
While I agree code should be self-documenting as often as possible, I suggest using these types of comments whenever possible (and more often than generic // comments). The /// XML comments are designed to work with IntelliSense, which can make development easier months down the line when you're trying to implement some library you built and don't quite recall how it works any longer. –  Matt DiTrolio Sep 21 '10 at 14:08
2  
And I think not only from an Intellisense perspective, from an automatic documentation generation perspective as well, xml comments are useful. But as with all comments, this only makes senses if the comments themselves are useful, and are adding to the self documented code. –  Vaibhav Sep 21 '10 at 14:44
5  
I agree that when you're writing public classes of an API or a framework, the coding standard should demand that you put comments in the code such that IntelliSense and documentation tools can plug into. But that's not all code. Aside from that concern, the approach I'm advocating here is, when you try to make your code cleaner and clearer, focus on the code itself, not the comment that describes the code. –  azheglov Sep 21 '10 at 16:31
3  
@JYelton: your comment misrepresents my answer. I implied more descriptive names, but not necessarily much more verbose ones, certainly not a 60-character identifier for a frequently called public function. Also, you have what seems to be a highly specialized function, but it takes a very general data type (XmlDocument) - that's one code smell. Then, your 60-character identifier describes "how" and not not "what" - of a public method. That's another smell. The main message is: think first about the code, not the comment. –  azheglov Sep 22 '10 at 2:02
2  
@JYelton The problem with your method name is not that it is descriptive, but rather it describes at least 2 separate operations and therefore should be refactored into at least 2 independent methods. –  Neal Sep 22 '10 at 3:18
show 2 more comments

We use StyleCop at work, which forces things like this, and makes me ueber-happy. Programmers can never agree on style, and forget to comment things. StyleCop is a pretty damn good whip.

share|improve this answer
add comment

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.

share|improve this answer
8  
Naming is one thing, but listing constraints on parameters or potentially thrown exceptions is still valuable. –  Anna Lear Sep 21 '10 at 13:56
    
Yes, I will concede you have a point, but most of the time the parameter constraints are obvious aren't they? –  John MacIntyre Sep 21 '10 at 14:11
    
Not sure I agree with John. With this logic, none of the .net framework methods should get any Intellisense help. –  Vaibhav Sep 21 '10 at 14:41
1  
@vaibhav - I did say "I would recommend using them on any public classes, methods, & properties in an API, library, etc..." ... that would cover what you're talking about doesn't it? –  John MacIntyre Sep 21 '10 at 15:06
1  
@John - strange, I could have sworn that I read something else altogether when I wrote that comment. Because your second paragraph is exactly what I said elsewhere in this thread. So, I must have rocks in my head for writing that comment. Yes, I agree with that. –  Vaibhav Sep 23 '10 at 13:40
show 3 more comments

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.

share|improve this answer
    
Stale comments can be considered a code smell though, even more so at the summary level. If other developers are changing functions and not updating the summary of what they are doing then one could argue they aren't documenting their work correctly. –  rob Mar 9 '11 at 3:19
add comment

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.

share|improve this answer
add comment

two or three years before, i believe must have details comments, but recently i prefer to more readable code than comments.

there are some more difficult to synchronize "///" and other comments with code, especially when code refactoring

share|improve this answer
add comment

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.

share|improve this answer
add comment

A good practice is use GhostDoc to create an initial sub for your method comments. This is a fantastic product which is free.

It's important to use comments because 9 out of 10 projects will come back to haunt you if don't add comments. At the time of writing the method it made sense, 6 months later might be a very different story.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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).

share|improve this answer
add comment

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.)

share|improve this answer
add comment

"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).

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.