如何在 Java 注释中标记代码的逻辑部分？

How to mark logical sections of code in Java comments?

提问by Frederik

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.

Java 类通常分为逻辑“块”。是否有约定来标记这些部分？理想情况下，它会得到主要 IDE 的支持。

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:

例如，在 Objective-C 代码中，您可以使用此方法：

#pragma mark -
#pragma mark Section name here

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

这将导致 XCode 中的菜单如下所示：

采纳答案by Olivier Croisier

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

我个人使用 80 个字符的行分隔符，如下所示：

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.

当然，这对于这么小的 POJO 来说似乎有点矫枉过正，但相信我，它在一些我必须浏览大型源文件并快速找到我感兴趣的方法的大型项目中证明非常有用。它还有助于理解源代码结构。

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.

在 Eclipse 中，我创建了一组生成这些条的自定义模板（Java -> 编辑器 -> Eclipse 首选项对话框中的模板），例如。- sepa（访问器的分隔符） - sepp（属性的分隔符） - sepc（构造函数的分隔符） - 等等。

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

我还修改了标准的“新类”模板（Java -> 代码样式 -> Eclipse 首选项屏幕中的代码模板）

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.

此外，还有一个名为Coffee-bytes的旧 Eclipse 插件，它增强了 Eclipse 折叠部分代码的方式。我不知道它是否仍然有效，但我记得可以通过添加特殊注释来定义任意可折叠区域，例如 // [SECTION] 或其他内容。它可能仍然适用于最近的 Eclipse 修订版，所以请看一看。

回答by artemb

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

最好通过继承或聚合将相关成员分组到单独的类中。这被认为是一种很好的 OOP 风格

回答by kukudas

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

当我使用 xcode 时，我也喜欢它。对于 Eclipse，我使用 ctrl+o（快速大纲）来浏览 Java 类。

回答by Teja Kantamneni

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.

在代码中使用不必要的注释/标记来帮助工作可能不是一个好习惯。我对 xcode 和 java 开发一无所知，但所有主要 IDE 的支持都支持在没有任何特殊标记的情况下查找成员，例如 eclipse 显示使用大纲视图的方法和成员，这些视图可以使用ctrl+OIntellij触发（我更喜欢在 mac 上使用更多，并且有一个社区版）具有相同的大纲概念，可以使用 (ctrl + f12) 快速访问。所以我的观点是不要在代码中使用任何不必要的标记，因为所有（或至少是好的/理智的）IDE 都可以自动完成。

回答by Thorbj?rn Ravn Andersen

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.

现代 IDE 允许您以多种不同方式查看代码，甚至可以重新组织它。Eclipse 甚至允许您在另一个面板中查看光标所在的代码的定义。

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.

如果你想分组，那么考虑把属于同一个类的东西放在一起，把不属于不同类的东西放在一起。

回答by basszero

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.

Eclipse 定义了一个@category javadoc 注释（滚动到标记为“类别支持”的部分），它可以在大纲视图中按类别进行过滤。不完全是你想要的。我很惊讶没有人写过一个 Eclipse 插件来提供像你的屏幕截图一样的视图。

回答by Lay González

If you can cluster your methods, do another class specifically for that concept that you want to capture in a section. Go ahead, creating files is free.

如果您可以对您的方法进行聚类，请为您想要在一个部分中捕获的那个概念专门做另一个类。继续，创建文件是免费的。

回答by user170317

For IntelliJ i do like:

对于 IntelliJ，我确实喜欢：

        public void ________________INIT__________________() {};

looking pretty in file structure!

看起来很漂亮的文件结构！

回答by Andrey Petrov

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

对于 intellij/android studio，有一个惊人的解决方案。
开始于：
//region Description
并结束于：
//endregion

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

快捷方式位于您可以使用Command+ Alt+ T(Mac) 或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)

如果需要，您还可以添加自己的线条以进行额外的视觉分离。该区域可以像任何功能一样使用 +/- 按钮随意收缩和扩展。您还可以使用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

回答by Manabu Tokunaga

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.

除了提供的 Andrey 的答案之外，为了使用 //region //endregion，我们在主要代码部分插入 [BigAscii 字母][1]。快速滚动时，它真的很突出。这种方法的一个缺点是我无法搜索它，因此您需要像我在下面所做的那样在“横幅”下方添加一个搜索词。

Blockquote

块引用

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

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

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