How do you use programming languages and frameworks to document your system design?

1 Code comments

Code comments are a great way to document your system design, as they provide text annotations that explain what your code does, why you wrote it, and how it works. This can help you and other developers understand and debug your code, as well as document your design choices and assumptions. However, if you don't update them regularly or follow a consistent style, code comments can become outdated, redundant, or misleading. Therefore, it's important to use code comments sparingly and wisely. You should use a standard syntax and format for your code comments, such as Javadoc, Doxygen, or NDoc. When writing code comments, focus on describing the purpose and logic of your code; avoid repeating what your code already says or what is obvious from the context. Additionally, use code comments to document design decisions, trade-offs, constraints, and dependencies. Don't forget to update your code comments whenever you change your code or design. Lastly, review your code comments periodically to remove any outdated, irrelevant or incorrect ones.

2 Documentation generators

Documentation generators are tools that can help you create consistent, structured, and comprehensive documentation for your system design with minimal effort. These tools extract information from your code comments, such as parameters, returns, exceptions, and references, and format them into HTML, PDF, or other formats. They can also generate diagrams, tables, indexes, and cross-references to help you visualize your system design. Popular documentation generators include Javadoc for Java, Doxygen for C++ and other languages, Sphinx for Python, and MkDocs for Markdown. Each of these tools produces HTML files from source code and comments as well as other formats such as LaTeX, RTF, or XML.

3 Frameworks and libraries

Frameworks and libraries are reusable code components that provide specific functionality or features for your system, helping you document your system design by following a common architecture, convention, or standard that is well-known and documented by the framework or library developers. Additionally, they can provide tools and templates to generate documentation for your system based on the framework or library structure and logic. For example, Django is a web framework for Python that follows the model-view-template (MVT) architecture and provides a built-in documentation system that generates HTML files from Python docstrings and reStructuredText files. Ruby on Rails is a web framework for Ruby that follows the model-view-controller (MVC) architecture and offers RDoc to generate HTML files from Ruby source code and RDoc comments. React is a library for building user interfaces with JavaScript that follows the component-based architecture and has React Docgen to generate documentation from React components and PropTypes. Bootstrap is a library for designing responsive web pages with HTML, CSS, and JavaScript that follows the grid system, with a comprehensive documentation website explaining its usage and customization of components and classes.

4 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?