Dive into adventures with XML documentation
Full time implementing can be hard, and working in a multilingual organization is sometimes exhausting. Still, when the going gets tough and the stakes are high, it is important not to lose sight of the end goal. Looking back, months or years later, it will truly be a memory of a lifetime.
XML Documentation Guidance
Very often we see the code from Microsoft not containing XML documentation, making it difficult to understand the meaning of the code itself. It's not that I cannot read and understand the code in a method, but it is always quicker to just read the Summary or Comment tags in the documentation instead of reading and dry-running code in your head.
XML documentation should provide information related to usage. It should help any programmer decide if they want to use the method and what the method is intended for. The following list provides best practice guidance for XML documentation.
- Add XML documentation with meaningful content.
- Use XML documentation to provide users and potential users with the information they need.
- Do not use XML documentation to discuss implementation details or other items not related to use.
- Do not add XML documentation for the sake of improving code coverage.
- Be aware of the methods with automatically generated XML documentation; for example, new and construct.
XML documentation is not the same as commenting code!
Comments should be used to describe the intent, algorithmic overview, and logical flow. Provide comments so that someone other than you (the original developer) can understand the behavior and purpose of the code. It is a best practice that most code will have comments reflecting the developers intent and approach for the code. Use comments liberally. Include comments that indicate who made the changes, when the changes were made, why the changes were added, and what the changes do. Comments are particularly beneficial when multiple parties are involved in modifying and maintaining code. The following table provides code commenting best practice guidance.
Do not use multi-line syntax /* … */ for comments. The single-line syntax // … is preferred even when a comment spans multiple lines. Its also quicker, mark a section of text and use the shortcut keys CTRL + K + C to comment out, and CTRL + K + U to uncomment.