Tools and Skills for .NET 8 - Chapter 6, Documenting Your Code, APIs, and Services

This chapter is about documenting your code, public APIs (Application Programming Interfaces), and services. Documentation improves code understandability, maintainability, team member onboarding, and the design of APIs and services, and is invaluable during debugging and support.

As well as documentation skills, we look at some tools for helping you produce documentation efficiently. DocFX is a powerful tool provided by Microsoft that can generate API documentation, conceptual documentation, and more from your source code and Markdown files.

Mermaid is a markup language and toolset for generating diagrams and charts, for example, sequence diagrams and flow charts. Combined with the Markdown markup language, it is quick and easy to write good-looking documentation. Most code editors have built-in support for markup languages like Markdown and Mermaid, or extensions and plugins that you can install.

Introducing documentation

Documentation is one of those practices in software development that can be a pain while you're doing it, but its benefits will improve the quality, maintainability, and longevity of your software.

The initial effort you put into documenting your code and APIs is an investment that pays dividends in the future, from making your code base more approachable and maintainable to ensuring knowledge transfer and facilitating debugging. It's a practice that not only benefits others but can also be a help to your future self.

As important as knowing the benefits of documentation, and the specifics of what and how to document that are covered in the rest of this chapter, is knowing when not to document.

Here are some scenarios where it might be justified to skip or minimize documentation:

• Prototyping and experimentation: When you’re rapidly prototyping or experimenting with new ideas, extensive documentation can slow down the process. The nature of a prototype is often temporary, meant to test ideas or approaches rather than to serve as a final product. In these cases, it might be sufficient to use only inline comments to clarify complex logic or decisions that aren't immediately obvious from the code itself.
• Self-documenting code: If the codebase is written with clarity in mind, using meaningful variable and method names, consistent architectural patterns, and clear structure, the code can often be self-explanatory. This approach argues that the best kind of documentation is the code itself. However, this doesn't replace the need for high-level documentation that explains the architecture and flow of the application, but it can reduce the need for detailed inline comments.
• Highly agile environments: In very agile settings where changes are frequent and rapid, maintaining detailed documentation can be less feasible. Here, the documentation effort might focus more on critical areas like APIs exposed to external users or complex algorithms crucial for the system's functionality, rather than documenting every internal service or method.
• Short-lived or temporary code: Code that is intended to be used temporarily or that will be replaced in the near term (for example, workaround patches and temporary fixes) might not be documented extensively.
• Internal tools for limited use: Tools or scripts intended for internal use among a small team, particularly if all members are familiar with the project's context, might not need extensive documentation. Communication and direct knowledge transfer might be more efficient in these contexts.
• Resource constraints: In some scenarios, especially within start-ups or small teams, resources and time are limited, and the priority might be set on delivering functional software to meet business needs. Documentation might be deprioritized in favor of more critical tasks.

However, even in these scenarios, it’s generally wise to at least document the intent and purpose of the software, key decisions that aren’t obvious, and any external APIs that other developers or systems might interact with.

You can learn more about my book, Tools and Skills for .NET 8, and pre-order it, at the following link: https://www.amazon.com/Tools-Skills-NET-practices-solutions/dp/183763520X/