Documenting Code and Results in MATLAB
Effective documentation is crucial for any engineering or scientific project. It ensures reproducibility, facilitates collaboration, and makes your work understandable to others (and your future self!). In MATLAB, this involves documenting your code, explaining your methodologies, and presenting your results clearly.
Documenting Your MATLAB Code
Well-commented MATLAB code is the foundation of good documentation. Comments help explain the purpose of your script or function, the logic behind specific sections, and the meaning of variables.
Use comments to explain your MATLAB code.
MATLAB supports two main types of comments: line comments (using '%') and block comments (using '%{ ... %}'). Line comments are ideal for explaining individual lines or short sections, while block comments are useful for longer explanations or temporarily disabling code.
Line comments start with the percent sign (%) and continue to the end of the line. They are used to explain specific lines of code, variables, or small logical blocks. Block comments, enclosed by '%{' and '%}', are typically used for longer explanations, function headers, or for commenting out larger sections of code. A good practice is to include a header comment at the beginning of each script or function that describes its purpose, author, date, and any input/output arguments.
Line comments (using '%') and block comments (using '%{ ... %}').
MATLAB also has a powerful tool called the 'Help browser' which can automatically generate documentation from specially formatted comments within your functions. This is known as 'Live Scripts' and 'Live Functions'.
Documenting Your Results and Methodology
Beyond code comments, it's essential to document your experimental setup, the data you used, the analysis steps, and the interpretation of your results. This ensures that your work is reproducible and can be validated by others.
Clearly document your experimental process and findings.
Documenting your methodology involves detailing the steps taken, the parameters used, and any assumptions made. For results, this includes presenting data visually (graphs, plots) and numerically, along with clear interpretations and conclusions.
When documenting your methodology, be specific. For example, if you used a particular sensor, specify its model and calibration. If you applied a specific algorithm, explain its parameters and why they were chosen. For results, use MATLAB's plotting capabilities to create informative figures. Label axes clearly, include legends, and provide descriptive titles. Accompany these visuals with textual explanations that summarize the key findings and their implications. Consider using MATLAB's 'Live Scripts' to combine code, output, and narrative text into a single, cohesive document.
Think of your documentation as a guide for someone else to replicate your entire project from scratch.
Tools for Documentation in MATLAB
MATLAB offers several features to aid in documentation:
| Feature | Purpose | Benefit |
|---|---|---|
| Line Comments (%) | Explain individual lines or short code segments. | Improves code readability and understanding. |
| Block Comments (%{...%}) | Explain larger sections or function headers. | Organizes code and provides detailed explanations. |
| Live Scripts (.mlx) | Combine code, output, and narrative text. | Creates interactive, self-documenting reports. |
| Function Help Text | Auto-generated documentation from function headers. | Provides instant help via the Command Window or Help browser. |
Live Scripts in MATLAB allow you to integrate executable code with rich text, including headings, paragraphs, equations, and visualizations. This creates a narrative flow that explains your analysis step-by-step, making your research easily understandable and reproducible. The output of your code, such as plots and tables, is displayed directly alongside the relevant code, providing immediate context.
Text-based content
Library pages focus on text content
Best Practices for Documentation
To ensure your documentation is effective, follow these best practices:
- Be Consistent: Use a consistent style for comments and explanations throughout your project.
- Be Clear and Concise: Avoid jargon where possible, and explain complex concepts simply.
- Be Complete: Document all essential aspects of your code and methodology.
- Update Regularly: As your code or analysis changes, ensure your documentation is updated accordingly.
- Target Your Audience: Consider who will be reading your documentation and tailor the level of detail.
To maintain accuracy and prevent confusion or errors for future users or collaborators.
Learning Resources
Official MathWorks documentation on how to use comments effectively in MATLAB code for better organization and readability.
Learn how to create interactive documents that combine code, output, and narrative text using MATLAB Live Scripts.
Understand how to write help text for your MATLAB functions, which can be accessed directly from the Command Window.
A blog post from MathWorks offering practical advice on writing clean, efficient, and maintainable MATLAB code, including documentation tips.
Explore how MATLAB tools and practices, including documentation, contribute to reproducible research in scientific and engineering fields.
General advice on technical documentation principles that are applicable to documenting MATLAB projects.
A video tutorial demonstrating the features and benefits of using MATLAB Live Editor for creating documented workflows.
A repository where users share MATLAB code. Many submissions include excellent examples of code and project documentation.
While not MATLAB-specific, this Coursera course covers essential principles of scientific communication and documentation applicable to research results.
Learn how to export and share your Live Scripts as various document formats like PDF, HTML, and Word.