C# comments on closing {}

Question

I've been working a little with DevExpress CodeRush and Refactor! Pro this week, and I picked up a commentor plug-in that will automatically generate comments as you type code.

I don't want to go into how good a job it does of picking out basic meaning (pretty good, actually) but it's default implementation does raise a question.

By default, typing a } character to close a block will result in the plugin adding a comment like the following...

using(MyType myType = new MyType())
{
    myType.doWork();
} // using

(i.e. adding a comment to the closing brace labelling where it was opened.)

While I can see that there are instances where this behaviour may be of great use, I feel that the resultant code looks very untidy with all the additional commenting.

I was wondering what other people;'s take on this kind of comment was. Not just from an academic standpoint, but if I get a good number of negative comments about them I can decide whether to inflict them upon my co-workers or strip them out.

Answer 1

I think comments like that are useless, unless of course the code is awful. With proper formatting of code it's not difficult to see where a block starts and where a block ends because usually those blocks are indented.

Edit: If a procedure is so big that is not readily apparent what block of code is being closed by a brace, then there should already be more descriptive comments describing the procedure anyways and these comments would just be clutter.

Answer 2

IMO every comment that is describing what the code is already telling you is unnecessary.

If you really have code blocks that are so long that you have to scroll a lot to see there beginning you have done something wrong and may consider to split the code up.

Answer 3

Maybe useful if the using block extends over a page in the IDE, but then you've got other problems to worry about. In this case I get by with proper indenting and an IDE that highlights the matching brace when I select one.

I give it a thumbs down in general, but with potential use when you can't avoid a long block otherwise.

Answer 4

This sort of comments are only usefull on very long blocks of code where you have many nested blocks. But that said this should not be the case in the first place as many nested blocks and long methods call for refactoring. So I don't like this at all, as the reader obviously can see what block of code it is.

Answer 5

Sometimes you will get very large code blocks, or a lot of nested blocks closing together. I sometimes use this style in cases like this, but definitely not all the time. I don't restrict it to code either: HTML can benefit greatly from this style of "close commenting":

<div id="content">
    <div id="columns">
        <div class="column">

            <!-- .. snip a lot of lines .. -->

        </div> <!-- .column -->
    </div> <!-- #columns -->
</div> <!-- #content -->

Answer 6

Bad bad comment style - it introduces a maintainance overhead in the codebase.

I've known ex-VB coders who found trails of }s in C-syntax code to be confusing, but in this scenario the real fix is to refactor your code to prevent deep nesting and excessively long functions and/or code blocks.

Answer 7

I find the idea of a plugin that genrates comments from code rather useless. If it can be inferred by the machine then it can also be inferred by anybody reading it. The comments are extremely likely to be totally redundant.

I feel that those closing brace comment is messy, it gives information that is better provided directly by the IDE if the individual wants it.

Answer 8

Don't do it, it simply adds noise if used all over the place, and besides proper indentation should solve the readability problem.

Answer 9

I would keep it turned off. I only see a point in using this when you have multiple blocks ending in the same place (longer or shorter blocks) - I've used them myself in some cases like these. However if they are used it would be better to add them manually, in carefully selected places rather than having some automated tool adding them.

Answer 10

I think more useful than comments would be an IDE feature to not only highlight matching pairs of braces, but also display the openining line on a tooltip, so that if you hovered over the closing brace in your example it would come up with "using(MyType myType = new MyType())" in a tooltip.

This would enable you to easily make sense of complex nested braces for large functions without providing constant visual clutter.

Answer 11

If you have to consider whether or not a certain type of comment is usable or not, it's most likely the latter.

Comments are for explaining certain blocks of code or an entity in its whole, to ease up on comprehension; not to make the formatting easier to read.

Having a plugin always conform to this behaviour is both obese and ugly.

Answer 12

I always find it useful to remember this...

Clear, well written code will provide enough of an explanation of what the code is doing for a competent programmer to pick it up.

Comments should be left in the code to explain why the code is doing it!

In other words, use comments to help the reader of your code understand the algorithm, or what the code is supposed to achieve, not how it's achieving it!

You might want to check out this post by Jeff Atwood.

Answer 13

I agree there are much better ways to describe what a code is doing.

If you have a long body of code preceded by a single informative comment like // Fix Work Item, you could take that code and refactor it as its own method. Then use the comment as the new method's name, FixWorkItem(). Doing this is a quick way to make your code more self-documenting and might even reveal some design characteristics you didn't notice before.

Keep an eye out for one-liner comments like that as potential refactors, which can be handled automatically by the IDE. Code that documents itself is better than even the best-written standalone comments, except of course when describing intent.