在 .NET(或常规)中创建文档的正确方法是什么?

Question

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

令我惊讶的是，~30% 的代码实际上是注释

<param name="">
<summary> 

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

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

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

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

Answer 1

举个例子...检查Microsoft参考源。

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

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

Answer 2

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

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

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