33

Is it an accepted practice in the Java programming language to end a brace for a code block with a comment that briefly explains what code block the brace closes off? I personally would think that they are useless comments that clutter the readability of the code, but perhaps I could be wrong. For example:

public void myMethod(int foo) {    
    // some code
    if (foo == 2) {
        for (int i = 0; i < myMax; i++) {
            while (true) {
                // some more code
            } // end while
        } // end for
    } // end if
} // end myMethod(int)

Is the practice of commenting code blocks in a similar manner an accepted practice?

ecbrodie
  • 11,246
  • 21
  • 71
  • 120
  • 3
    Wait till you have several inner blocks, seperated by 10's or even 100's of lines...then it helps. Think about what it would look like if you had some other `if` statements within the loop... – MadProgrammer Oct 09 '12 at 02:29
  • 36
    If you have 100's of lines within a block you should probably consider pulling a method out of there and making everything simpler. – digitaljoel Oct 09 '12 at 02:33
  • I personally feel that its good practice to end brace blocks with suitable comments. It makes my code more understandable with least possibility of confusion about scopes. – exexzian Oct 09 '12 at 03:24
  • 2
    When I do this, I increase the information slightly, for example `} // end for i` to distinguish it from a nested `} // end for j` – Henry Oct 09 '12 at 11:31
  • 3
    If your code is so confusing that it makes you feel you should re-introduce oldskool if-endif syntax, then you should make your code less confusing. :) – Joren Oct 09 '12 at 11:53
  • 1
    This is what vim's `%` is for (sort of), as well as folding (sort of). Comments are unnecessary. – Izkata Oct 09 '12 at 18:04
  • 2
    I think that Linus Torvalds said "If your code has more than three levels of indentation, then it's not a good piece of code". That said, comments at the end of code blocks may be a sign of over complexity in your code... keep it simple, it will help you (and those who read your code) have a good time – Barranka Oct 11 '12 at 19:56
  • I find that putting the opening brace on a line by itself, at the same indentation as the closing brace, is the most effective way of keeping track of which braces are matched. But that is a whole separate discussion that people get really fired up about... – Kip Oct 11 '12 at 22:31
  • Sometimes code is complicated and then it can help you. But you should not add comments like this to every closing brace. Btw: your question is not only for Java. It applies to all programming languages that use braces. – Krisztián Balla Nov 21 '13 at 07:24

6 Answers6

58

My take on it is that as a rule it is NOT a good practice. As always with rules there could be exceptions but very rare.

It is not a good practice because

  1. Modern editors highlight the opening bracket when you place cursor on the closing one and vice versa.
  2. Most important: if there is a possibility to not see the beginning of the clause it means that the method is huge (more than half a page) which is a bad practice.
  3. It adds noise to the code that will confuse readers who are used to more conventional Java coding style.
  4. Incorporating LordScree-Joachim Sauer comment: These comments will be pain in the neck to maintain. So most likely it will not be maintained and the information will usually be out of sync with reality.
farfareast
  • 2,179
  • 1
  • 23
  • 22
37

This is not exactly a bad practice, BUT it is a deadly side effect of poor Object-Oriented coding practice!

Also, this violates style guidelines and the tenets of "self-documenting code". You should never have that many brackets or a method long enough to confuse the reader about bracket placement, instead encapsulate that functionality in another method that is well documented.

Brackets imply either looping or complex if-else logic chains, good programming practice is to have a method do exactly one thing and do it well, then build your program from these smaller, atomized methods. I would read Butler Lampson's seminal piece "Hints for Computer System Design". It goes into some of the details on how to design good software.

So essentially, don't comment like this because:

  1. It violates style guidelines
  2. It shows poor Object-Oriented programming - atomize your functionality!
  3. It is a deadly side effect of coding practice which goes against the underlying concepts of why Java was created - encapsulation, specifically information hiding
  4. It violates the concept of self-documenting code
  5. Other programmers will make fun of you.
Josiah Hester
  • 6,065
  • 1
  • 24
  • 37
3

I only do this when there is a place in code that has a lot of closing braces after each other. But not for every brace. Mainly I seem to use it for loops so that you can easly see what is a repeated code block.

Something that looks like this:

            // ...
            file.Close();
          }
        }
      }
    }
  }
}

Then it helps to add some comments:

            // ...
            file.Close();
          }
        }
      }
    }//for: each file
  }
}
Krisztián Balla
  • 19,223
  • 13
  • 68
  • 84
1

It depends on how complicated the method or function is. Like if you have something that can be easily read and understood than there really wouldn't be a point in ending EVERY line with a comment that explains that the part has ended. That's what indentation and line breaks are for. However if you have something that is truly complex and affects a major part of your code then you should denote where that code ends and what that section does.

VinceOmega
  • 105
  • 1
  • 11
0

If there are nested blocks of same kind, it may be confusing instead of doing good. Let's say you have 4 or 5 nested if statements(keep in mind that this only an example to demonstrate the situation, regardless of "oh you should separate those" or "make a method" suggestions) in that case you will have 4 or 5 different //end if sequenced. After a while, it makes you confuse which "end if" is for which statement, makes you spend extra effort unconsciously to see through the actual code/statements because it's not always as clean/short as your example.

baturayd
  • 19
  • 2
0

IMO, It does not help much. The code inside a loop or an if statement should not be too big. It would have helped if there were 500 lines inside the loop.

fastcodejava
  • 39,895
  • 28
  • 133
  • 186