类描述中要写什么答案

【问题标题】：What is to be written in the class description类描述中要写什么
【发布时间】：2016-05-20 12:37:52
【问题描述】：

如何描述一个类是我的问题？当您在 bluej 中开始上课时，总会有一个文档注释来说明该课程的描述。该描述中要写什么？

例如，我有一个名为 Economy 的类，它扩展了一个抽象类 Structure，而抽象类 Structure 实现了一个接口 Basic。那么我应该在类经济的描述中写什么呢？

【问题讨论】：

想象您的开发人员正在寻找可能帮助您完成任务的课程。然后你会找到Economy 的班级……现在你想知道什么？也许这门课的目的？它应该如何使用？如果它是不可变的和/或线程安全的（这对于您的目的来说可能太多了）和其他东西。想想其他开发人员以及他们需要了解的有关您的课程的内容。那就写吧。
我建议从 JDK 和其他库中检查现有的 Javadoc，以了解类描述中的有用内容。
@Tom 但我从来没有真正理解到底要写什么.....你能举个例子吗......也许还有其他例子。
en.wikipedia.org/wiki/Javadoc
@Stefan .......我可以写我的经济舱基本上找出乘坐飞机经济舱旅行的费用......但我认为这是描述我在课堂上使用过的方法

【解决方案1】：

首先要理解的是......实际上应该尽可能少地编写 cmets。取而代之的是：编写可以阅读、理解和使用的代码，而无需（大量）额外的 cmets。

示例：您选择“结构”和“基本”的名称非常……毫无意义。这些名称并没有说明人们可以从相应的类和接口中获得的预期行为。

事情是：cmets 撒谎。它们为您的源代码增加了额外的质量；但不能自动检查的质量。因此，该信息很容易与代码真正所做的事情不同步。

换句话说：在一个类上放置一个空的或非常简短的描述是完全可以的。此外：还有SRP 为您提供指导，让您在每个班级中“只放一个责任”。因此，“类描述”的核心点是命名/描述相应类的一项职责。

【讨论】：

我能不能写我的经济舱基本算出坐飞机的经济舱旅行的费用……不过我想这是我在我用过的方法的描述类
另一个很好的例子：你的名字“经济”丝毫没有暗示它是关于计算费用的。如果您真的有兴趣学习如何以更好的方式做事，我建议您在网上搜索 Robert Martin 的“敏捷原则和模式……在 C# 中”。该书的 PDF 可从网上获得……并仔细查看他提出的“案例研究”。仅仅阅读第 26 章可能会让您了解如何仅通过良好的类/接口命名来告诉您发生了什么。
我应该写这个，因为它是我项目 Airline Booking 的一部分 ,,,, 让我简单地向你解释一下这个项目：
我应该使用它，因为它是我项目 Airline Booking 的一部分让我简要地向你解释一下这个项目：我应该创建一个接口 Basic 来声明我将使用的所有方法.然后是实现接口的抽象类结构，并具有所有接下来三个类（即经济、商业、高级经济）的通用方法。例如。方法 name() 很常见，所以在这里使用。现在 3 个单独的类扩展了类结构并找到了乘飞机旅行的费用。所以这是我的项目，这就是为什么我应该将类命名为经济

【解决方案2】：

想想如果有人想使用你的课程，他们需要知道什么，或者如果他们不知道你的课程是做什么的，你会给他们一个基本的描述。为什么有人会使用你的课程？它有什么作用？

@Jägermeister 提到了代码 cmets 是多么容易出错，因此请确保无论您编写什么代码，都要根据您的代码所做的事情进行更新。如果您更改课程，请确保您也更改了对课程的描述。并保持您的描述相当简短，您很可能只需要几行或更少。

如果您发现自己写了几行描述，最好看看您的课程，然后问问自己它是否做得太多。在这种情况下，让另一个类接受它的一些职责可能是个好主意。

【讨论】：