函数的注释是否应该包含其调用的函数完成的工作的描述？

Question

假设我有一个名为 DisplayWhiskers() 的函数，它在屏幕上放置一些斜杠和反斜杠来代表动物的胡须，如下所示： /// \\\. 我可能会为这个函数写一条评论，大致如下

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

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

一方面，我似乎应该能够查看 DisplayKitten() 的注释，并了解我需要了解的有关它将做什么的所有信息，包括确切地显示胡须的方式。我不必去其他地方阅读 DisplayWhiskers() 的注释来找到这一点。

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

什么被认为是最佳实践？

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

Answer 1

一般来说，注释不应集中于代码的作用——代码本身记录了这一点。相反，他们应该专注于为什么要做这些事情。