language-agnostic - 函数/类注释格式约定

Question

谁拥有最易读和最有用的函数/类注释约定？我不是在寻找可以生成文档的东西，但我正在考虑采用 JavaDoc 之类的东西，因为所有信息都在那里。

/**
 * This function processes data
 * 
 * @param p1 the first piece of data
 * @param p2 the second piece of data
 * @return   true if the processing was successful, else false
 */
function ProcessData(p1, p2){

还是其他手工制作的东西？

/////////////////////////////////
// This function processes data
//
// p1    the first piece of data
// p2    the second piece of data
// returns true if processing was successful, else false
function ProcessData(p1, p2){

单行注释优于多行注释有什么合理的论据吗？

我想对我使用的所有语言应用一个约定，所以请分享您拥有的任何特定于语言或与语言无关的约定！

Answer 1

对于评论风格，我肯定会选择多行，因为这就是它们的用途 - 整体看起来更干净。

对于参数，第一个更强大，因为您可以指定每个信息的类型：'@type name description'，vs'name description'，这是我通常在 C 类型语言中看到的。

Answer 2

Python 使用RST。

您也许可以使用Sphinx，它可能会做您想做的事。

Answer 3

我建议根本不要评论，而是给 p1 和 p2 赋予有意义的不言自明的名称。

正如这里所说，“评论不是辛德勒的名单。它们不是纯粹的善。它们充其量是必要的恶”