在.NET（或一般）中创建文档的正确方法是什么？

Question

我刚刚开始我的软件开发职业生涯，我得到了第一个了解它的项目。

让我感到非常惊讶的是，事实上~30％的代码实际上都是评论

<param name="">
<summary> 

等等。我认为.NET开发者知道我的意思。

关键是，它使这段代码变得非常难看。我知道它有助于Swagger制作文档，它有助于IDE描述方法及其参数，但是......它也使代码变得丑陋。

这是常见做法吗？或者它可以以不同的方式完成？

顺便说一句，我知道它可以隐藏在IDE中，但这不是我要问的问题。

Answer 1

只是举个例子......检查Microsoft Reference Source

文档是必要的，如果你不这样做，它看起来很丑陋。可理解/可维护的代码是适合每个人的好代码。

你不能离开它，你绝不能。

Answer 2

在代码中包含文档注释，如下所示是编写文档的首选方法。按照这种方法，开发人员可以在他们的IDE中阅读文档，或者可以为Web生成HTML版本。

/// <summary>
/// An effective trap for capturing delicious, tasty roadrunners.
/// </summary>
public class RoadrunnerTrap
{
}

话虽如此，您还可以清楚地命名您的类，变量和方法，并避免编写尽可能多的文档。没有文档通常是坏的，但太明显或重复文档更糟糕。