在函数中使用KDoc/Javadoc注释是否被认为是错误的做法？

Question

我经常发现在类或函数中使用KDoc/Javadoc注释而不是普通注释是有帮助的。默认情况下，IntelliJ对它们进行了更明显的着色，更重要的是，允许超链接到定义。我想知道这样做是否被认为是不好的做法。

例如：

/**
 * Standard kdoc comment here...
 */
fun saveUser(user: User) {

    /**
     * Save the user to the [UserRepository]
     */
    userRepo.save(user)
}

在内部注释中，[UserRepository]将链接到该类的类型定义。这个例子有点勉强，但我经常发现它在读取代码中很有用。

Answer 1

你问“这是否被认为是糟糕的做法”，答案是肯定的。

但并不是因为在不适当的地方使用了KDoc/Javadoc语法，而是因为注释的级别。如果您感到必须在某些方法中对代码进行注释，请考虑重写代码以获得更好的可读性。

在你的例子中

fun saveUser(user: User) {

    /**
     * Save the user to the [UserRepository]
     */
    userRepo.save(user)
}

你的评论是多余的。对于任何理智的开发人员来说，userRepo.save(user)都是完全可读的，就像“将用户保存到存储库”一样，因此可以简单地删除注释。

你谈论连接的可能性。在userRepo变量上，任何合适的IDE都将显示其声明的类型，并允许您导航到变量定义和类源，因此这种链接也是不必要的(而且它只适用于在规范以外的地方接受KDoc/Javadoc的非标准IDE )。

当然，在某些情况下，您的评论可能不像您的示例中那样琐碎。但是，如果您的代码如此晦涩以至于需要这样的注释，那么您最好重写它，或者重新构造它，用合理的名称调用较小的方法，并提供在那里添加KDoc/Javadoc的机会。

Answer 2

这么做是没用的。KDoc或JavaDoc的目的是运行一个工具来生成如何使用代码的HTML。工具的工作方式是扫描特定位置上的特殊格式的注释(即方法声明和类声明)。

根据用于扫描这些注释的工具，您有两种潜在的可能性：

• 扫描仪会混淆并生成错误的文档。
• 这些注释被忽略，并被简单地当作普通注释来处理。

我的建议是简单地在您的方法/函数中使用常规注释。许多语言中的标准多行注释如下所示：

/* This is a multiline
 * comment
 */

实际上，Javadoc表示法是一个标准的多行注释，因此编译器可以忽略它，而额外的*可以调用此注释用于生成文档页的工具。