Why should you document your code and how can it improve your workflow?

1 Benefits of code documentation

Code documentation can help you and others to save time and effort by avoiding confusion and errors when reading, modifying, or debugging your code. It can also share your knowledge and expertise with colleagues, collaborators, or clients by explaining the logic, purpose, and functionality of your code. Additionally, code documentation can enhance the quality and reliability of your code by following standards, conventions, and best practices for code documentation and testing. Moreover, it can increase the value and impact of your code by making it more accessible, reusable, and adaptable for different scenarios and applications.

2 Types of code documentation

Code documentation can be divided into two main types: internal and external. Internal documentation includes comments and annotations written within the code to describe each line, function, or module, as well as how and why it is important. For example, using # in MATLAB or // in C for single-line comments, or %{ %} in MATLAB or /* */ in C for multi-line comments. On the other hand, external documentation consists of documents and resources created outside the code to provide instructions and examples for using it. These documents can include README files, user manuals, tutorials, or websites to document the code for target audiences such as users, customers, or reviewers.

3 Tools for code documentation

Code documentation can be done manually or with the help of various tools and software, such as integrated development environments (IDEs) like MATLAB Editor, Simulink Editor, or Visual Studio Code, which offer features like syntax highlighting, code completion, code formatting, and code analysis. Documentation generators like Doxygen, Sphinx, or MATLAB Report Generator can also extract comments and annotations from your code to generate external documentation in different formats. Furthermore, testing frameworks like MATLAB Unit Testing Framework, Simulink Test, or Google Test can help verify the correctness and performance of your code by writing and running test cases and generating test reports.

4 Tips for code documentation

Code documentation is an ongoing process that requires planning, execution, and revision. To ensure successful documentation, start as early as possible and update regularly. Adhere to the principles of DRY and KISS by avoiding redundant, irrelevant, or complex information. Use clear, concise, and consistent language and style throughout your project. Explain the assumptions, limitations, and dependencies of your code, and provide examples and references when necessary. Document for different levels of detail and abstraction depending on the needs of your audience. Finally, review and test your code and documentation regularly while soliciting feedback from peers, mentors, or clients. Make sure to fix any errors, inconsistencies, or gaps in your code and documentation based on the feedback.

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