For years I’ve been storing XML documentation inline in my source code and putting up with a “sea of green”, but I recently found out about the <include file="..." path="..."/> directive that can be used in Visual Studio to move documentation into it’s own XML file. Apparently intellisense will still work using this method, as will Sandcastle etc for help file generation.
I was just wondering how others are handling the “sea of green” issue where code gets buried under mounds of documentation? Do you just learn to live with it, or do you move the XML documentation into a separate file and use inline comments where code clarification might be needed?
Pros
- The code file becomes a lot “cleaner”.
- It makes it easier to browse the code and locate a specific code block/method.
Cons
- It may make the code harder for strangers to grok if there is no inline documentation.
- The absence of documentation may create a tendency to forget about the XML file and not update documentation when the code changes.
I just leave it inline and use these Visual Studio – Command to collapse all sections of code? commands to collapse and expand code when I’m looking through large files. In this case I think the cons outweigh the pros. Unless you and your fellow developers are extremely diligent about documentation I don’t see that method working very well. Documentation is already lacking in most code bases I’ve seen, so increasing the difficulty of adding it, in my opinion, is a bad idea.