How to mark logical sections of code in Java comments?

Question

Java classes are generally divided into logical "blocks". Is there a convention to mark these sections? Ideally, it would be supported by the major IDEs.

I personally use this method:

//// Section name here ////

However, some editors seem to have problems with this.

As an example, in Objective-C code you can use this method:

#pragma mark -
#pragma mark Section name here

This will result in a menu in XCode that looks like this:

Answer 1

As far as I know there is no such thing as a supported specification for grouping class members together. You can use what-ever comment convention you like, but chances are it will not be supported by any tool.

It is better to group related members into separate class via inheritance or aggregation. This is considered a good OOP style

Answer 2

I liked that also when i was using xcode. For eclipse i use ctrl+o (quick outline) to navigate through a Java class.

Answer 3

Using unnecessary comments/markers in the code to help working may not be a good practice. I have little idea about xcode and java development but all major IDE's support finding the members with out any special markers like eclipse shows the methods and members using outline view which can be triggered using ctrl+O, Intellij (which I prefer using more on mac and had a community edition too) has the same outline concept and can be quickly accessed using (ctrl + f12). So my point here is don't use any unnecessary mark up in the code as all (or atleast good/sane) IDE's can do it automatically.

Answer 4

I personally use 80-chars line separators, like this :

public class Client {

    //================================================================================
    // Properties
    //================================================================================

    private String name;
    private boolean checked;

    //================================================================================
    // Constructors
    //================================================================================

    public Client() {
    }

    public Client(String name, boolean checked) {
        this.name = name;
        this.checked = checked;
    }

    //================================================================================
    // Accessors
    //================================================================================

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public boolean isChecked() {
        return checked;
    }

    public void setChecked(boolean checked) {
        this.checked = checked;
    }

}

Of course, this may seem a bit overkill for such a small POJO, but believe me, it proved very useful in some huge projects where I had to browse through big source files and quickly find the methods I was interested in. It also helps understand the source code structure.

In Eclipse, I have created a set of custom templates (Java -> Editor -> Templates in Eclipse's Preferences dialog) that generate those bars, eg. - sepa (SEParator for Accessors) - sepp (SEParator for Properties) - sepc (SEParator for Constructors) - etc.

I also modified the standard "new class" template (Java -> Code Style -> Code Templates in Eclipse Preferences screen)

Also, there is an old Eclipse plugin called Coffee-bytes, which enhanced the way Eclipse folds portions of code. I don't know if it still works, but I remembed one could define arbitrary foldable zones by adding special comments, like // [SECTION] or something. It might still work in recent Eclipse revisions, so take a look.

Answer 5

A modern IDE allows you to view your code in many different ways, and even reorganize it. Eclipse even allows you to view the definition of the code you have the cursor on in another panel.

Any automatic reorganizing of your code, will cause such markup to break down.

If you want grouping then consider putting things belonging together in the same class, and things not belonging together in different classes.

Answer 6

Eclipse defines an @category javadoc annotation (scroll to section marked "Category support") which enables filtering by category in the outline view. Not exactly what you want. I'm suprised nobody has written an Eclipse plugin which offers a view like your screen shot.