How can you write concise code documentation?

1 Use a style guide

A style guide is a set of rules and standards for writing code and documentation. It can help you create consistent, readable, and organized documentation across your projects. You can use an existing style guide, such as Google's or Microsoft's, or create your own based on your preferences and needs. A style guide can cover aspects such as formatting, naming, syntax, comments, annotations, and structure of your documentation.

2 Write for your audience

Your code documentation should be tailored to the needs and expectations of your audience. For example, if you are writing for end users, you should focus on how to use your code, what features it offers, and what problems it solves. If you are writing for other developers, you should explain how your code works, what design choices you made, and what assumptions you made. You should also use appropriate language, tone, and level of detail for your audience.

3 Use clear and concise language

Your code documentation should be easy to understand and follow. You should use simple and precise words, avoid jargon and slang, and explain any acronyms or technical terms. You should also use active voice, avoid passive voice, and use short and direct sentences. You should avoid unnecessary repetition, redundancy, and filler words. You should also proofread and edit your documentation for grammar, spelling, and punctuation errors.

4 Comment your code wisely

Comments are lines of text that explain your code and are ignored by the compiler or interpreter. They can help you and other developers understand the logic, purpose, and functionality of your code. However, comments should not be used to replace good code. You should write clear and meaningful code that expresses your intent and follows the naming conventions of your language. You should also avoid commenting obvious or trivial things, such as what a variable or function does. You should comment only what is not obvious or requires further explanation.

5 Use documentation tools

Documentation tools are software applications that can help you generate, organize, and maintain your code documentation. They can extract information from your code, such as comments, annotations, parameters, and return values, and format it into a readable and searchable document. They can also help you create diagrams, tables, examples, and links to enhance your documentation. Some examples of documentation tools are Doxygen, Sphinx, Javadoc, and DocFX.

6 Update your documentation regularly

Your code documentation should reflect the current state of your code. If you make changes to your code, such as adding, deleting, or modifying features, you should also update your documentation accordingly. You should also review your documentation periodically and check for accuracy, completeness, and relevance. You should remove any outdated, incorrect, or unnecessary information from your documentation. You should also solicit feedback from your users or peers and improve your documentation based on their suggestions.

7 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?