Pet*_*lly 21 .net stylecop xml-comments ghostdoc
我在一个团队中工作,我们在StyleCop中使用了广泛的规则集,我想知道关于这样一个工具停止有用并且开始变得烦人的一般观点的想法.我们还使用GhostDoc,因此代码中充斥着XML注释,这使得代码更难以阅读并因此进行审查.我对XML注释没有任何问题,并且发现它们在某些地方非常有用,但它们是否真的需要在每个字段和属性上？
我们有一个令人钦佩的目标:"每个项目在构建时必须有0个警告"但当然这个目标需要违背合理的StyleCop规则集,否则会浪费宝贵的时间来"修复"StyleCop警告的原因.
有什么想法？
编辑 我现在真的想知道什么是像ALL ALL的stylecop工具的论据？为什么不放弃它,让合理的编码标准和良好的代码审查来处理其余的事情？特别是在一支优秀的团队中？当然,获得0警告的任务实际上会增加价值,因为所有警告都是相关的.
我认为GhostDoc的唯一优势是它可以为您从头开始编写XML注释节省大量时间.我不认为你应该接受生成的评论而不进行编辑 - 这可能适得其反.
这是由GhostDoc生成的xml注释满足的Stylecop规则(SA1642:ConstructorSummaryDocumentationMustBeginWithStandardText)的组合 - 是否在一天结束时添加任何值？
/// <summary>
/// Initializes a new instance of the <see cref="SomeCustomType"/> class.
/// </summary>
/// <param name="someParameter">The someParameter.</param>
public SomeCustomType(string someParameter)
{
}
bob*_*nce 24
我认为这更像是一个咆哮而不是一个问题,但我同意你的看法:
虽然显然应该有源代码格式化指南,但过度规范的不可破坏的规则会导致令人不快的极端情况.在所有情况下严格遵守规则可能会产生难以理解的杂乱或过度包装的代码.
编码是各种各样的写作,因此奥威尔的奖金规则 - "打破任何这些规则,而不是说任何直接的野蛮" - 需要也适用于编码风格指南.
我怀疑自动化风格执行是一个好主意,在一个能够设置和理解风格指南的合格程序员团队中.自动lint对于捕获意外错误非常有用,但如果采用高度规范性的法律进行代码格式化,则无法考虑Orwell的规则.使用强大的规则集,这可能会迫使您在可维护性的幌子下编写维护较少的代码.
如果你的团队中有一些不太称职的编码员,除非被迫进入风格,他们的输出是混乱的,那么执法可能是一个好主意.(但那时你可能遇到了更大的问题!)
我之前没见过GhostDoc,但实际上我有点震惊.
在他们自己的头版上的例子:
/// <summary>
/// Determines the size of the page buffer.
/// </summary>
/// <param name="initialPageBufferSize">
/// Initial size of the page buffer.
/// </param>
/// <returns></returns>
public int determineBufferSize(int initialPageBufferSize) {
几乎是错误评论的典型示例,对其记录的代码完全不加了解.这绝对比没有评论文件更糟糕.
随后,Javadoc之后的所有in-source-doc模式都有点令人怀疑,因为它们使用通常针对最终用户的材料使源代码混乱 - 与阅读代码的人完全不同.但这是绝对的坑.我无法想象谁认为这是一个好主意.
Dan*_*zey 14
StyleCop是一个工具.它不应该是完美的开箱即用,它不应该满足每个人的需求.
我个人说"是的,这很重要" - 因为当你运行一个开发团队时,StyleCop会帮助你确保遵守你的编码指南.这正是它的目的:以自动化,可测量的,一致的方式评估编码标准.如果你不想在你的构建过程中做到这一点,那么你是对的 - 这是浪费时间.
你自己说:零警告目标"需要反对合理的StyleCop规则集".运行任何配置不符合您需求的工具都没有意义.如果一条规则对你来说是"烦人的",那就把它关掉 - 但对于其他人来说这可能是非常重要的.
至于你的"确实增值"问题:是的.人们低估了一致性的价值.如果所有构造函数都具有相同的注释样式,那么如果项目中属性的所有Intellisense具有相同的结构,那么处理它的精神障碍就会减少一个(无论多小).使用可自动化的工具,几乎不需要付出任何努力.有什么可抱怨的？