函数/类注释格式约定
谁拥有最具可读性和最有用的函数/类注释约定？ 我不是在寻找生成文档的东西，但我正在考虑采用像 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){
单行注释比多行注释有什么合理的论据吗？
我想对我使用的所有语言应用一个约定，因此请分享您拥有的任何特定于语言或与语言无关的约定！
Who has the most readable and useful function/class commenting convention?
I'm not looking for something that generates docs, but I'm considering adopting something like JavaDoc because all the info is there.
/**
* 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){
or some other hand crafted thing?
/////////////////////////////////
// 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){
Any reasonable argument for single line comments over multiline?
I'd like to apply a convention to all languages I use, so please share any language-specific or language-agnostic conventions you have!
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
对于评论风格，我肯定会选择多行，因为这就是它们的用途 - 它整体看起来更干净。
对于参数，第一个更强大，因为您可以指定每个信息的类型：'@type name description'，与'name description'，这是我通常在 C 类型语言中看到的。
For the comment style, I would definitely go for multiline, as that's what they are for - it just looks cleaner overall.
For the params, the first one is more powerful, as you can specify the type of each information: '@type name description', vs 'name description' and it's what I usually see in C type languages.
Python 使用 RST。
您也许可以使用 Sphinx，它可能会做您想要的事情。
Python uses RST.
You might be able to use Sphinx, it might do what you want.
我建议根本不要发表评论，而是为 p1 和 p2 赋予有意义的不言自明的名称。
正如这里所说，“评论不是辛德勒的名单。它们并不纯粹是好的。它们充其量只是一个必要之恶”
I suggest not commenting at all, but instead, giving meaningful self-explanatory names to p1 and p2.
As said here, "comments are not schindler's list. They are not pure good. They are, at best, a necessary evil"