java - 一个函数的注释是否应该包括它调用的函数完成的工作的描述？

Question

假设我有一个名为 DisplayWhiskers() 的函数，它在屏幕上放置一些斜杠和反斜杠来表示动物的 mustache ，如下所示:///\\\。 我可能会按照以下方式为此功能写评论

// Represents an animal's whiskers by displaying three  
// slashes followed by a space and three backslashes

但是，如果我随后添加函数 DisplayKitten() 和 DisplaySealion()，作为其工作调用 DisplayWhiskers() 的一部分，那么这些其他函数的注释中应该包含多少关于 mustache 显示的详细信息？

一方面，我似乎应该能够查看 DisplayKitten() 的注释并了解我需要了解的关于它将要做什么的一切，包括它如何显示 mustache 。我不应该去其他地方阅读 DisplayWhiskers() 的评论来找出这一点。

另一方面，如果 DisplayKitten() 的注释明确引用三个斜杠后跟三个反斜杠，这似乎违背了封装的精神，并且如果 DisplayWhiskers() 后来被更改可能会出错。

什么是最佳实践？

编辑:几个答案表明解决方案是阅读代码。我理解好的代码本身就是最好的注释的原则，但是对于这个问题，我并不是要引用代码内的注释，而是要引用函数原型(prototype)附带的头文件中的注释。我们假设实际代码是预编译的，想要使用或调用它的客户无法访问。

Answer 1

我会说你应该清楚地编写你的代码并适本地命名，这样它就可以 self 记录，并且不需要注释来让 future 的程序员理解它的作用。然后，您只能使用注释来记录 API 函数(用户无权访问代码库)或您无法重构以使其更易于理解的复杂/不明显的内容。