在.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
{
}

话虽如此，您也可以清楚地为类，变量和方法命名，以开始并避免编写过多的文档。没有文档通常很糟糕，但是过多的明显或重复的文档会更糟。