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

Answer 1

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.

Answer 2

For intellij/android studio there is an amazing solution.
Start with:
//region Description
and end with:
//endregion

The shortcut for that is in the menu you can open with Command+Alt+T (Mac) or Ctrl+Alt+T (Windows)

You can also add your own line for additional visual separation if you need it. The region can be contracted and expanded at will with the +/- buttons like any function. You can also navigate between regions with Command+Alt+Period (Ctrl+Alt+Period)

Source.

Example:

//region Parceler Implementation
//---------------------------------------------------------------------------------------
@Override
public int describeContents() {
    return 0;
}

@Override
public void writeToParcel(Parcel dest, int flags) {
    dest.writeParcelable(this.die, 0);
    dest.writeParcelable(this.dieSprite, 0);
}

private DieVm(Parcel in) {
    this.die = in.readParcelable(Die.class.getClassLoader());
    this.dieSprite = in.readParcelable(Sprite.class.getClassLoader());
}

public static final Parcelable.Creator<DieVm> CREATOR = new Parcelable.Creator<DieVm>() {
    public DieVm createFromParcel(Parcel source) {
        return new DieVm(source);
    }

    public DieVm[] newArray(int size) {
        return new DieVm[size];
    }
};
//---------------------------------------------------------------------------------------
//endregion

Answer 3

In addition to Andrey's answer provided, to use //region //endregion, we insert [BigAscii letters][1] in major code sections. When scrolling fast, it really stands out. One drawback of this approach is that I cannot search for it so you'd need to add a search term just below the "banner" like I do below.

Blockquote

//    _      _____          _____                  _   _
//   | |    |  __ \   /\   |  __ \      /\        | | | |
//   | |    | |  | | /  \  | |__) |    /  \  _   _| |_| |__
//   | |    | |  | |/ /\ \ |  ___/    / /\ \| | | | __| '_ \
//   | |____| |__| / ____ \| |       / ____ \ |_| | |_| | | |
//   |______|_____/_/    \_\_|      /_/    \_\__,_|\__|_| |_|
//
//   Search here with: LDAP Auth

[1]: http://patorjk.com/software/taag/#p=display&c=c%2B%2B&f=Big&t=LDAP Auth

Answer 4

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 5

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.