功能/类注释格式约定

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

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

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

Answer 2

Python使用RST。

您可以使用Sphinx，它可能会执行您想要的操作。

Answer 3

我建议不要评论，而是给p1和p2提供有意义的自解释名称。

如上所述here，“评论不是辛德勒的名单。他们不是纯粹的好。他们充其量只是一种必要的邪恶”