有没有办法（插件或工具）强制代码评论？ [英] Is there a way (add-in or tool) to force code commenting?

问题描述

大家好！



我在挑战中需要一些帮助！



i有一个团队（大约6个人）但他们没有记录代码的文化。

要解决它，我正在寻找任何工具或加载项来做到这一点（在构建时抛出异常）代码元素没有记录）



我查了一些工具：



1- CodeIt。对（我的雇主很贵）

2- CodeRush（不符合我的期望）

3- StyleCop（仅限C＃，我们使用vb.net）

3- FxCop（不符合我的期望，只适用于组装）



等...



有人知道任何工具或加载项（最好免费）只强制代码文档！？！



非常感谢

解决方案

没有自动处理可以取代人类文化。



想一想：如果你在现有的代码中添加注释tuation很简单：如果这是自动完成的，那么这个评论是微不足道的，因此无用。我实际上只能看到一个排除：如果所有块结尾位置（结束，}）被评论以匹配开头，我觉得很方便，甚至这是有问题的。当我在每种类型和方法之前看到标准注释块时，我发现它非常恼人。这是一个典型的例子：

  ///   < span class =code-summarycomment><  摘要 >  
   ///   InitializeUi方法初始化UI 
   ///   <   / summary  >  
   ///   <   param     name =scenarioGenerator >  ScenarioGenerator参数<   / param  >  
   ///   <   param     name =logicEngine >  LogicEngine参数<   / param  >  
   ///   <   param     name =scenarioGenerator < span class =code-summarycomment>>  ScenarioGenerator参数<   / param  >  
   ///   <   param     name =skinManager >  SkinManager参数<   / param  >  
   void  InitializeUi（
 ScenarioGenerator scenarioGenerator，
 LogicEngine logicEngine，
 ScenarioGenerator scenarioGenerator，
 SkinManager skinManager）{
  //   ...  
} 

它只污染代码并激怒读者，没有别的。它告诉你你已经是什么知道了。生成此注释本身可能很有用，但前提是开发人员向其添加了一些有用的信息，例如，它可以用于XML文档。但即使这样做也很少，选择公共实体。



同时，自动生成的代码的一些简约评论很有用，但你是谈论开发者的文化，所以这不是你关心的，正如我所理解的那样。



这应该让你知道自动评论是邪恶的。它仍然有用，但前提是通过适当的发展文化调节。记住古老的说法：代码应该是自我评论。实际上，应该由评论大师的手添加一些罕见的评论。所以，如果想到执行评论的想法出现在你的脑海中，那么考虑一下：你自己有这种文化吗？



我可以告诉你什么可以没有这种文化就会发生开发人员将忽略自动注释。这个评论要么根本不出现，要么更糟糕，纯粹是自动的，不受开发者的影响。当然你将无法强制执行任何事情。

-SA

我们使用了 GhostDoc [ ^ ]半自动生成文档。



Daniel对此发布 [ ^ ]列出了我听说过的其他一些（我也使用过Doxygen而不是其他的） ）



但我会建议引入Code Review - 否则你会得到无意义的评论，只是为了让工具保持安静。



我发现板球棒也有帮助。

Hi guys!

I need some help in a my challenge!

i have a team (about 6 guys) but they don't have the culture of documenting the code.
To solve it, i'm looking for any tool or add-in to do this (throwing exceptions on build when the code element is not documented)

I've checked some tools:

1- CodeIt.Right (expensive for my employer)
2- CodeRush (does not meet my expectation)
3- StyleCop (only for C#, we use vb.net)
3- FxCop (does not meet my expectation, it is only for assemblies)

Etc...

Someone know's any tool or add-in (preferably free) only to force the code documentation!?!

Thanks a lot

解决方案

No automatic processing can replace human culture.

Think of this: if you add comments to existing code, the situation is simple: if this is done automatically, this comment is trivial and hence useless. I actually can see only one exclusion: I find it convenient if all end-of-block places ("end", "}") are commented to match the beginning, and even this is questionable. I find it extremely irritating when I see a standard comment block before every type and method. This is a typical example:

/// <summary>
/// InitializeUi method Initializes UI
/// </summary>
/// <param name="scenarioGenerator">ScenarioGenerator parameter</param>
/// <param name="logicEngine">LogicEngine parameter</param>
/// <param name="scenarioGenerator">ScenarioGenerator parameter</param>
/// <param name="skinManager">SkinManager parameter</param>
void InitializeUi(
    ScenarioGenerator scenarioGenerator,
    LogicEngine logicEngine,
    ScenarioGenerator scenarioGenerator,
    SkinManager skinManager) {
    //...
}

It only pollutes the code and irritates the reader, nothing else. It tells you what you already know. The generation of this comment itself can be useful, but only if the developer adds some useful information to it, that it can go, for example, to XML documentation. But even this should be done very rarely, to select public entities.

At the same time, some minimalistic comments of the auto-generated code is useful, but you are talking about developers' culture, so this is not your concern, as I understand.

This should give you the idea that automatic commenting is evil. It still can be useful, but only if it is mediated through proper development culture. Remember old saying: code should be self-commenting. Indeed, some rare comments should be added, by a hand of a master of comments. So, if the idea to "enforce" commenting came to your mind, how about thinking at this: do you have this culture yourself?

I can tell you what can happen without such culture. The developers will simply ignore the automatic commenting. This commenting will either not appear at all, or, much worse, will be there, purely automatic, untouched by a developer's hand. And of course you won't be able to "enforce" anything.

—SA

We've used GhostDoc[^] to semi-automate production of documentation.

The response by Daniel to this post[^] lists some others I've heard of (I've used Doxygen as well but not the others)

However I would suggest introducing Code Review - otherwise you'll get meaningless comments inserted just to keep the "tool" quiet.

I find a cricket bat helps too.

这篇关于有没有办法（插件或工具）强制代码评论？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！