Is there a coding convention for a "line rule" for Java

Question

I like to organize my Java files a little and would like to know if there is a standard way of doing this. For example:

public class Example
{
    private int exampleInt;
    private String exampleString;

    /*------------------------------------------------------------*/
    /* I N N E R   C L A S S E S                                  */
    /*------------------------------------------------------------*/
    private someInnerClass 
    {
            someInnerClass()
            {
            }
    }
    /*------------------------------------------------------------*/

    /**
    * This method returns the example int.
    */
    public int getExampleInt() {
            return exampleInt;
    }
}

I don't what to call the part where I have a sort of comment break /-----------------------------------------------------------------/ Is there any sort of convention for this sort of thing? Or is this something that I should just not be doing because most IDE's will display everything nicely to you in some sort of outline view?

Answer 1

The code explains itself. There is no need to put these ugly long comment lines in. If you really have to, then make them short, like so:

// -------------
// Inner Classes
// -------------

This is less messy. When I come across these kind of comments that state the obvious, I usually remove them right there and then.

Answer 2

You should take a look at the comment conventions for the Javadoc tool, Netbeans and other IDE's are used to take them as the main description of how your code works and it should outline it without problem

How to Write Doc Comments for the Javadoc tool

Answer 3

Refactoring and source cleanup may cause your source files to be reorganized, including comments.

I would suggest you do not do that since that comment may end up somewhere completely unrelated.

Another thing you may want to try instead is to use your IDE to reformat your source. Eclipse allows for doing that every time you save a file. This will give all your code a consistent look allowing for easier reading.

Answer 4

Here's something to think about: If someone on your team doesn't want to follow your comment break convention, what's to stop them from putting their methods wherever they like? And if they did misplace a method, how would you find it? Comment breaks don't force compliance, so you can't trust them. So, if you're going to end up using your IDE's nice features to find methods, why not just do that from the start?

To summarise, yes, you can do that if you want but it's not a reliable way of dividing up your code.

Answer 5

I would recommend removing those line comments. They only clutter thing. Whitespace is even more effective IMO, because it sets off blocks of code visually and doesn't make a mess of the source.

Answer 6

I tend to find comments like the ones in your example as an eye sore. If you are grouping your inner classes that is enough; there is no reason for the extra noise. Furthermore, any respectable IDE (Eclipse, IntelliJ, etc.) will list, filter, and group the structural elements of your code for you.

Answer 7

To answer your question, I don't believe there's any such convention.

Sun's Code Conventions for Java certainly mentions no such thing.

My recommendation is simply don't do it. On my projects, we simply provide properly formatted JavaDoc comments at the type level, and method level JavaDoc for key API methods (mainly public methods on interfaces) and concrete methods when a particular implementation is special enough to be worth documenting.

This is something that I think junior developers (myself included) love to do, but come to realize later that it's an additional burden that doesn't really add that much value.

Answer 8

I know of no universally accepted convention for section delimiters. Some people like them (I happen to be one of those people), others find them to be an unnecessary distraction. Neither group is right or wrong: it's a matter of personal taste that unfortunately can become a near religious issue for some developers (not unlike choice of editor, choice of language, etc.).

I think that the important thing is to be consistent and respectful of other developers, especially in the absence of a project-wide standard. If you aren't the primary maintainer of a certain file but need to make a change there, try your best to follow whatever format is already in place.

Answer 9

Make the code clear and drop unnecessary comments. The code should state what it does by itself, document the public class/interface, constructor & methods which are part of the API, make it clear and concise/short.