16

是否有维护模式注释的项目？

例如，当我编写一个构建器时，我想用@Builder.

以这种方式进行注释可以立即清楚地了解代码实现了什么。此外，@Builder注解的 Javadoc 可以参考构建器模式的解释。此外，从构建器实现的 Javadoc 导航到@BuilderJavadoc 可以通过@Builder使用@Documented.

我正在放慢为我的代码中的模式和习语积累一小组此类注释的速度，但我想利用一个更完整的现有项目（如果存在）。如果没有这样的项目，也许我可以通过将其拆分为单独的模式/习语注释项目来分享我拥有的东西。

更新：我创建了Pattern Notes 项目来响应这个讨论。欢迎投稿！这是@Builder

4

10 回答 10

7

这对我来说似乎是对注释的滥用。当然，我可以理解为什么您可能想注意一个类正在帮助实现的设计模式，但是只使用 Javadoc 和/或类的名称似乎更合适。您正在使用的模式的名称对代码本身并不重要......模式只是解决问题的常用方法的指南。注释就足够了，而不是为您使用的每个模式创建一个新文件。

于 2008-09-24T15:03:14.703 回答
6

这是一个有趣的解决方案，但我一直想知道您要解决的真正问题是什么？或者换句话说，你从使用这样的东西中得到了什么，而你在课堂上对它的使用进行了适当的评论却没有得到什么？

我可以想到一些缺点，但除了这是一种很好的标准化代码文档方式之外，我想不出其他好处。

缺点是，即：

  1. 程序员要考虑的另一件事，这绝不是一件好事
  2. 未注释的模式可能会令人困惑 - 有人可能忘记记录它，但也许它不是模式..？
  3. 你真的能注释所有模式吗..？那些不依赖于单个类/方法的模式，例如三层架构模式，或线程池，甚至 MVC 呢？
于 2009-04-23T21:40:19.307 回答
5

Michael Hunger 和我已经启动了一个用于注释的开源项目，以指定类所属的模式。我们正处于起步阶段，但很想听听您的意见。

我想采用 KISS 原则，以使人们尽可能容易地使用注释。例如，如果你正在编写一个适配器，你可以简单地说：

@AdapterPattern
public class EnumerationIteratorAdapter<T> implements Enumeration<T> {
  ...
}

当然，您可以根据需要指定更多信息，例如角色、参与者和评论。我们希望这将使开发人员更容易清楚地标记他们的类。

项目主页位于http://www.jpatterns.org，您还可以从中访问初始源代码树。如果您想为该项目做出贡献，请通过 javaspecialists dot eu 与我联系。

Heinz（Java 专家时事通讯）

于 2010-07-28T06:33:13.697 回答
4

我刚刚偶然发现了另一篇对您来说很有趣的文章：Design Markers - Explicit Programming for the Rest of Us，其中讨论了标记接口，例如Serializable.

用他们的话来说：

...仅仅因为一个类声明它“实现了 Serializable”并不意味着它已经正确地实现了 Serializable 契约。

由于 Java 无法真正判断合同是否已得到满足，因此使用标记接口更像是程序员的明确承诺。

标记界面被忽视的好处是它们还记录了应满足合同的意图......

 

为什么设计选择传统上没有记录在源代码中？主要是因为没有明确的地方放置它们。

即使每个“类型安全枚举”类都有注释指出它遵循该模式，也不会添加任何详细说明（更不用说教程信息），因为必须重复复制它，或者更糟糕的是，将其零星地放置在任意位置。

在创建附加到每个 Design Marker 接口的 JavaDoc 注释时，可以比典型的更详细，因为注释不需要在其他任何地方重复。

他们还提到了一些缺点，这是一个很好的思考！

于 2009-10-09T13:51:57.297 回答
3

更好的是使用注释来实际构建构建器的样板。让我们面对它最标准。

@Builder("buildMethodName")
Class Thing {
  String thingName;
  String thingDescr;
}

典型用途：

Thing thing =
      new Thing.Builder().setThingName("X").setThingDescr("x").buildMethodName();
于 2009-12-03T21:56:41.923 回答
3

首先，您要做的是记录意图（或意图s）。

那么，为什么不使用注释的通用版本，例如使用@Documented的@UsePattern 之类的标记注释（来自 IBM 的不错的教程）？我不喜欢的是注释在运行时保留，除非您想影响程序语义，否则这是一种浪费。

或者看起来更合适的自定义 Javadoc 标记。

关于比较的一些信息：Comparing Annotations and Javadoc Tags with a nice one sentence summmary：

<<一般来说，如果标记是为了影响或产生文档，它可能应该是一个 javadoc 标记；否则，它应该是一个注释。>>

关于文档作为注释或 javadoc 标签也存在/曾经有过一些争论。

于 2009-10-07T09:54:21.253 回答
1

对我来说，这似乎是对注释的滥用。除非打算使用这些注释来实现行为，否则我会使用 KISS 原则：Plain ol' javadoc 可以很好地记录工件应该做什么/应该做什么；用于扩展 javadoc 的自定义 doclet；对于那些想知道 X 或 Y 模式是什么（或网络上某个地方的链接）的人来说，谷歌。

对于大多数模式，都有出色的、准官方的解释。为什么要自己写？是否有对项目至关重要的其他信息？使用注释确保可以从一个类的 javadoc 导航到自定义编写的模式 javadoc 就像 CEO 组建了一个开发团队来创建一个包含两个现有季度报告总数的报告的故事 - 这太难了（而且更便宜）每年用计算器将两者相加 4 次：-/

于 2010-04-08T20:58:07.453 回答
1

另外还有这篇 2008 年计算机科学论文：Java 和 AspectJ 中的设计模式实现，它在 OOPSLA 2008 上发表，应该可以说明它的质量。

一个很好的报价：

...仅仅存在专门包含模式代码的类就可以作为正在使用的模式的记录。在 AspectJ 案例中，我们观察到两个额外的改进。首先，与特定模式实例相关的所有代码都包含在单个模块中（定义参与者、分配角色等）。这意味着模式实例的整个描述都是本地化的，并且不会在系统中“丢失”[21] 或“退化”[7]。其次，在当前的 AspectJ IDE 支持下，所有引用、建议方法等都是超链接，允许开发人员概览角色分配以及感兴趣的概念操作在哪里……

于 2009-10-13T13:38:02.080 回答
0

如果您还可以编写一个注释处理器来验证模式的某些属性 - 例如在实现模式时检查常见错误 - 这将非常有用。编译器和程序员的文档。

于 2009-08-18T11:01:06.963 回答
-2

首先，这是一个非常好的主意，我只是在这里闲逛，因为我搜索了一个“设计模式注释”库。很好，我找到了这个！我会检查它并尽快给予反馈。

致所有怀疑论者：很抱歉，你们中的大多数人在设计模式的话题上并不是很有经验。例如，Martin Harris 的帖子从 09 年 12 月 3 日 21:56 开始......我了解您想要保持您的“示例”简单。但这不是设计模式意义上的构建器。

我想对那些根本看不到有用性的人说同样的话。如果类与它们在设计模式中的角色的关系被注释到类中，我可以使用生成器来制作样板代码。我在源代码中看到类顶部的所有关系，并且可以使用我的 IDE 快捷方式导航到相关类。

如果你学会了用模式思考并且所有模式在源代码中都很明显（通过注释或注释），你可以在不到一个小时的时间内掌握一个由 200 个类组成的系统。

关于使用@UsePattern() 或@Builder("buildMethodName") 等建议......在这里我们不得不问，如何让它“typesave”？毕竟这些字符串很容易出现拼写错误。

正确注释的一个优点是您可以注释角色……大多数设计模式不是由单个类（如 Singleton）组成，而是由几个一起工作的类组成！例如，如果您有一个构建器，则结果（用@Product 注释）也可能是一个@Composite。因此，构建器组合在一起的部分将是@Component（关于@Composite）和一个@Part（关于@Builder 和@Product）。

此类注释的最佳论据可能是 java.lang.class，因此您可以表达这一点。

无论如何，只是一些想法......我迫不及待地想回家玩你目前拥有的东西^^

于 2010-07-08T14:01:48.357 回答