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

【问题标题】：How to mark logical sections of code in Java comments?如何在 Java 注释中标记代码的逻辑部分？
【发布时间】：2011-01-23 15:58:33
【问题描述】：

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

我个人使用这种方法：

//// Section name here ////

但是，一些编辑似乎对此有疑问。

例如，在 Objective-C 代码中你可以使用这个方法：

#pragma mark -
#pragma mark Section name here

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

【问题讨论】：

作为一名iOS开发者，这是我刚开始使用Android Studio时最怀念的地方
downvoted：使用现代 IDE 和语言，这是一种糟糕的做法。如果您必须对代码进行分段，您可能已经违反了单一职责原则，最好将其拆分为不同的类/文件。如果有多个编辑器，它可能会在一段时间后不同步，因为有些人会遵循这一点，有些人会重构和重新组织代码，或者自动保存和格式化操作会破坏它。
否决：我同意@f.carlsen。如果你用 cmets 组织你的类，你很可能会破坏Single Responsibility Principle。
致仇恨者：当 Java 支持 Swift 风格的类扩展时打电话给我，您可以在逻辑上将接口实现分成不同的部分。是的，一个类可以很好地同时实现多个接口。

标签： java comments

【解决方案1】：

据我所知，没有支持将类成员分组在一起的规范。您可以使用任何您喜欢的评论约定，但它可能不受任何工具的支持。

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

【讨论】：

拆分代码段似乎只有理论上是可能的。例如，使用具有名称等属性的类 Client 和集合“发票”。我希望能够将其拆分为包含名称的 getter/setter 的“名称”部分和包含发票的添加/删除方法的“发票”部分。将这些拆分成一个类层次结构似乎不切实际，每个类只能添加一个属性，即“NamedEntity”、“NameAndAddressEntity”、“Invoicable”、...

【解决方案2】：

我在使用 xcode 时也喜欢这一点。对于 Eclipse，我使用 ctrl+o（快速大纲）浏览 Java 类。

【讨论】：

【解决方案3】：

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

【讨论】：

同意，部分标记只会增加视觉混乱。你的班级应该足够专注，让这些事情变得无关紧要。
当然，但是将方法分组到逻辑和标记部分可以帮助将视觉顺序强加到原本是平面方法列表的方法上。有时您并不确切地知道您想要哪种方法，但最好同时采用所有相关方法，并且知道您正在查看相关代码的全部范围。

【解决方案4】：

我个人使用 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;
    }

}

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

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

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

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

【讨论】：

【解决方案5】：

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

对代码的任何自动重组都会导致此类标记失效。

如果您想要分组，请考虑将属于同一类的东西放在一起，将不属于同一类的东西放在不同的类中。

【讨论】：

【解决方案6】：

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

【讨论】：

然而，在大多数 java 视图中，可以根据类别过滤类成员，以隐藏为默认的 getter 和 setter，例如。
不知道为什么我不能在 Android Studio 中使用@category，你知道我可以做些什么来实现同样的行为吗？

【解决方案7】：

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

【讨论】：

【解决方案8】：

对于 IntelliJ，我确实喜欢：

        public void ________________INIT__________________() {};

文件结构看起来很漂亮！

【讨论】：

这似乎是一个非常糟糕的解决方案。当您的目标是代码组织时，为什么还要声明其他方法？
就是让整个文件在结构视图中分段。
这只是一个真正在 android studio 中看起来的，建议你自己作为答案，我会使用
我见过的最糟糕的事情！它是公开的！ o_O
这是显示在结构视图中的唯一答案，并且适用于不同的 IDE。将其设为私有并微笑并忍受它，或者如果您不喜欢它，请不要使用它，但不要通过将其否决而将其隐藏在其他读者之外。

【解决方案9】：

对于 intellij/android studio，有一个很棒的解决方案。
开头：
//region Description
并以：
//endregion

结尾

快捷方式在菜单中，您可以使用 Command+Alt+T (Mac) 或 Ctrl+Alt+T（Windows）

如果需要，您还可以添加自己的线条以进行额外的视觉分隔。区域可以像任何功能一样使用 +/- 按钮随意收缩和扩展。您还可以使用 Command+Alt+Period（Ctrl+Alt+周期)

Source.

例子：

//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

【讨论】：

这非常有用谢谢安德烈。顺便说一句，我正在使用 Eclipse 键盘快捷键布局，我认为这些快捷键不适合我，但“// 区域”效果很好
我在结构视图中看不到任何显示方式，所以我仍在使用假的空成员（以及抑制未使用的警告）。
有什么方法可以在 Android Studio 中显示这些区域（结构视图）？
链接已失效；这个IntelliJ IDEA blog 可能是一个有用的参考。它还提到了NetBeans-like style folding items<editor-fold ...>。
最佳答案

【解决方案10】：

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

块引用

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

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

【讨论】：

【解决方案11】：

我会使用javadoc;或将以下内容用作简单的“分隔符”（单行或 3 行）：

/** RecyclerOnItemClickListener */

/** 
 * RecyclerOnItemClickListener
 */

因此在 IDE 中，它以不同于不显眼的注释灰色的颜色显示。

【讨论】：