将XML文档存储在内联或单独的文件中？

Question

多年来，我一直在我的源代码中内嵌XML文档，并提出了“绿色之海”，但我最近发现了可以在Visual Studio中使用的<include file="..." path="..."/>指令文档到它自己的XML文件中。显然intellisense仍然可以使用这种方法，Sandcastle等也可以生成帮助文件。

我只是想知道其他人是如何处理代码被埋在文档堆中的“绿色之海”问题的？您是刚学会使用它，还是将XML文档移动到单独的文件中并使用可能需要代码澄清的内联注释？

赞成

• 代码文件变得更“干净”。
• 可以更轻松地浏览代码并找到特定的代码块/方法。

缺点

• 如果没有内联文档，可能会让陌生人更难以编写代码。
• 缺少文档可能会导致忘记XML文件而不会在代码更改时更新文档。

http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx

Answer 1

我只是保留内联并使用这些Visual Studio - Command to collapse all sections of code?命令在我查看大文件时折叠和扩展代码。在这种情况下，我认为缺点超过了专业人士。除非您和您的开发人员对文档非常勤奋，否则我认为这种方法效果不佳。在我看到的大多数代码库中已经缺少文档，因此在我看来，增加添加代码的难度是一个坏主意。