Shr*_*ree 4 c++ documentation code-comments
如何保持源代码的良好记录/评论？是否有工具为Unix平台上的C++生成注释框架？
一般来说,对于包含大约100行代码的文件,建议使用多少行注释？
Mic*_*ent 44
一般来说,最好让代码本身解释什么它做,而评论是有来形容,为什么它是这样的.没有数字可以坚持.如果您的100行代表自己说话,请不要发表评论或只是在开头提供摘要.如果涉及的某些知识超出了代码的范围,请在评论中解释.
如果您的代码太复杂而无法解释,那么这可能是重构的原因.
这样,当您更改实现时,您也不需要更改注释,因为您的注释不会复制代码.由于设计的原因很少改变,因此为了清楚起见,在评论中记录它们是安全的.
Sta*_*Man 15
就个人而言,我认为骷髅评论是一个可怕的,可怕的想法.我知道有时候保存几次击键并且可能在评论中得到参数签名是很好的...但是产生n + 1空无用的评论(当编辑器添加了样板并且编码器已经将它们保留原样时)更加令人恼火.
无论如何,我确实认为需要评论 - 如果只有代码一次编写对于解释来说太微不足道,那么代码的可能性是无用的(即可能是自动化的,不需要手写).我倾向于合理地评论我的代码,因为我已经了解到通常我自己首先需要它.其他人可以使用它们只是一个额外的好处.
tpd*_*pdi 12
一般来说,对于包含大约100行代码的文件,建议使用多少行注释？
足以使你的意图清楚,并解释任何使用不熟悉的习语.没有经验法则,因为没有两行100行代码是相同的.
例如,在C#中,可以为属性提供如下的setter和getter:
public int ID { get; set; }
在两周前我加入StackOverflow之前,我甚至都没有看过任何C#,但即使对我来说也不需要评论.评论说
// accessor and setter for ID property
只会是噪音.同样的,
for( int i = m ; i < n; ++i) { // "loop from m to n" is a pointless comment
char* p = getP() ; // set p to getP, pure noise.
if( p ) // if p does not eqaul null, pure noise
int a &= 0x3; // a is bitwise or'd with 0x303, pure noise
// mask off all but two least significant bits,
//less noisy but still bad
// get remainder of a / 4, finally a useful comment
同样,任何有能力的编码员都可以阅读代码,看看它在做什么.任何具有基本经验的编码人员都知道这if( p )是一个常见的习语if( p != 0),不需要解释.但除非你发表评论,否则没有人能读懂你的意图.
评论你想要做什么,你做的原因,而不是代码明显做的事情.
在编辑时:你会注意到在11天后,没有人在我的一个示例评论中评论故意错误.这只是强调该评论是纯粹的噪音.