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

Question

Java类通常被划分为逻辑“块”。是否有一种标记这些部分的惯例？理想情况下，它应该得到主要IDE的支持。

我个人使用以下方法：

//// Section name here ////

然而，有些编辑器似乎在此方面存在问题。

以Objective-C代码为例，您可以使用这种方法：

#pragma mark -
#pragma mark Section name here

这将在XCode中生成一个菜单，看起来像这样：

- Frederik

---

作为一名iOS开发者，当我开始使用Android Studio时，我最怀念的是这个。 - Chris Chen

被踩了：使用现代IDE和编程语言，这是一种不好的做法。如果你必须对代码进行分段，那么你很可能已经违反了单一职责原则，最好将其拆分到不同的类/文件中。如果有多个编辑器，它很可能在一段时间后失去同步，因为有些人会遵循此方法，有些人会重构和重新组织代码，或者自动保存和格式化操作会破坏它。 - f.carlsen

被踩了：我同意@f.carlsen的观点。如果你用注释来构建你的类，很可能会违反单一职责原则。 - schrieveslaach

对于那些抱怨的人：当Java支持Swift风格的类扩展并且你可以将接口实现逻辑分离到不同的部分时，再来找我吧。是的，一个类可以同时实现多个接口。 - William Entriken

点赞。即使类已经只有一个职责，将其组织起来仍然是一个好的实践。例如，我喜欢将每个接口的实现放在单独的部分中。 - fishinear

Answer 1

对于Intellij/Android Studio，有一个惊人的解决方案。
从以下开始：
//region Description
并以以下结束：
//endregion 在菜单中按下快捷键Command+Alt+T（Mac）或Ctrl+Alt+T（Windows）。你也可以添加自己的行来进行额外的可视分割。

区域可以像任何函数一样通过+/-按钮随意收缩和扩展。你还可以使用Command+Alt+Period（Ctrl+Alt+Period）在区域之间导航。

参考：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

- Andrey Petrov

---

这非常有用，谢谢Andrey。顺便说一下，我正在使用Eclipse键盘快捷方式布局，但我不认为快捷方式适用于我，但'// region'非常好用。 - ThinkBonobo

我没有看到任何方法可以在结构视图中显示它，所以我仍然使用虚假的空成员（以及抑制未使用警告）。 - Tom

有没有办法在Android Studio（结构视图）中显示这些区域？ - MiguelHincapieC

链接已失效；这篇IntelliJ IDEA博客可能是一个有用的参考。它还提到了类似于NetBeans风格的折叠项<editor-fold ...>。 - Franklin Yu

最佳答案 - Michał Ziobro

Answer 2

我个人使用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折叠代码段的方式。 我不知道它是否仍然可用，但我记得可以通过添加特殊注释（如// [SECTION]或类似注释）定义任意可折叠区域。 它可能仍然适用于最近的Eclipse版本，所以请看一眼。

- Olivier Croisier

Answer 3

Eclipse定义了一个@category javadoc注释（滚动到“Category support”部分），可以在大纲视图中按类别进行过滤。不完全符合您的要求。我很惊讶没有人编写Eclipse插件，提供像您屏幕截图那样的视图。

- basszero

---

在大多数 Java 视图中，可以根据它们的类别过滤类成员，以便默认隐藏 getter 和 setter 等内容。 - Riduidel

我不知道为什么在Android Studio中无法使用@category，你知道我该怎么做才能实现相同的行为吗？ - MiguelHincapieC

Answer 4

我在使用Xcode的时候也很喜欢这个功能。对于Eclipse，我使用ctrl+o（快速大纲）来浏览Java类。

- kukudas

Answer 5

我会使用javadoc或者以下的简单 "分隔符"（一行或三行）：

/** RecyclerOnItemClickListener */

/** 
 * RecyclerOnItemClickListener
 */

这样在IDE中，它会显示为与不引人注目的灰色注释不同的颜色。

- superarts.org

Answer 6

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

- Teja Kantamneni

---

同意，章节标记只会增加视觉上的混乱。你的类应该足够紧凑，使这些东西变得不相关。 - Paul McKenzie

当方法分组为逻辑和标记的部分时，可以帮助对本来是一份扁平的方法清单施加视觉秩序。有时您不确定所需的确切方法，将相关的方法一起查看，并了解您正在查看相关代码的全部范围是非常好的。 - Brian Rak

Answer 7

除了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 Auth

这是一个关于LDAP认证的链接，可以帮助您在C++中进行身份验证。请点击链接查看详情。

- Manabu Tokunaga

Answer 8

据我所知，目前没有支持将类成员分组的规范。您可以使用任何您喜欢的注释约定，但很有可能不会被任何工具支持。

最好通过继承或聚合将相关成员分组到单独的类中。这被认为是良好的面向对象编程风格。

- artemb

---

将代码分成不同部分似乎只是在理论上可行。例如，以一个名为“Client”的类为例，该类具有诸如姓名和收集发票等属性。我希望能够将其拆分为一个包含名称的部分，其中包含名称的getter / setter，以及一个包含发票的部分，其中包含添加/删除发票的方法。将它们拆分成每个类仅能添加一个属性的类层次结构似乎不切实际，比如“NamedEntity”、“NameAndAddressEntity”、“Invoicable”等。 - Frederik

Answer 9

现代的集成开发环境可以让你以多种不同的方式查看你的代码，甚至重新组织它。Eclipse甚至允许你在另一个面板中查看光标所在代码的定义。

任何自动重组你的代码，都会导致这样的标记崩溃。

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

- Thorbjørn Ravn Andersen

Answer 10

如果你可以对方法进行分类，那就另外创建一个类来专门捕捉你想在这一段中捕捉的概念。尽管创建文件是免费的，请放心使用。

- Lay González