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

【问题标题】：What is the proper way of creating documentation in .NET (or general)?在.NET（或一般）中创建文档的正确方法是什么？
【发布时间】：2019-01-30 00:56:29
【问题描述】：

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

让我非常惊讶的是，大约 30% 的代码实际上是带有

的 cmets

<param name="">
<summary>

等等。我认为 .NET 开发人员明白我的意思。

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

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

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

【问题讨论】：

标签： c# .net rider

【解决方案1】：

只是给你一个例子......检查Microsoft Reference Source。

文档是必要的，如果您不这样做，对其他人来说会很丑陋。可理解/可维护的代码是适合所有人的好代码。

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

【讨论】：

【解决方案2】：

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

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

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

【讨论】：