Coding Guidelines: where to start?
A pragmatic approach to improve the quality of a large code base.
Published: 2025-07-25
Cleaning Up Large MATLAB Codebases Step by Step
Introduction
A large, messy codebase is usually not the result of bad engineering. More often, it's the natural outcome of years of growth: new features, changing requirements, multiple contributors, different coding styles, missing guidelines, and very commonly, a lack of tests.
Over time, these factors introduce friction. Code becomes harder to read, harder to change, and riskier to maintain. Everyone feels the pain, yet improving the situation can seem daunting. The practical way forward is to start incrementally, following the Boy Scout Rule: leave the code better than you found it.
In this article, the focus is on incrementally adopting coding guidelines in existing MATLAB codebases. While coding standards are the main theme, other relevant aspects of gradual refactoring, such as testing, automation, and tooling, will also be touched upon briefly.
The Mindset: Boy Scout Rule
The guiding mindset is the Boy Scout Rule: leave the code better than you found it. When you fix a bug, also take the opportunity to refactor the code you touch. Even if you only spend time understanding an unfamiliar section, you can still improve its documentation and style.
One of the core principles when improving a (large) codebase is incremental change. During an initial assessment using a coe checker (like CC4M) you will often discover hundreds or even thousands of guideline violations. It is neither realistic nor necessary to fix everything at once. Time and budget for refactoring are limited, and improvements usually need to happen alongside regular development work.
That is exactly where the Boy Scout approach fits: small, continuous improvements applied whenever the code is already being modified. Over time, these minor clean-ups accumulate into substantial quality gains without requiring disruptive, large-scale rewrite efforts.
CC4M and the Boy Scout Rule
This incremental approach is supported by CC4M in several practical ways. In addition to providing multiple guideline sets that can be aligned with different stages of code modernization, CC4M includes specific features that are explicitly designed to enable gradual improvement instead of large, disruptive clean-ups:
- Targeted file analysis: CC4M can analyze a predefined set of files, allowing teams to focus only on the code they are currently modifying.
- Scoped folder analysis: CC4M can analyze selected folders using include and exclude patterns compatible with MATLAB’s dir command behavior. This makes it possible to improve one module or subsystem at a time.
- Change-focused reporting via CLI: The CC4M command-line interface can report violations only on changed lines or modified code blocks (such as functions or property sections). This directly operationalizes the Boy Scout Rule by encouraging developers to improve only what they touch, keeping effort proportional and manageable.
Before You Can Start
1. Establish Coding Guidelines
This step does not need to be complicated, and it is usually better if it isn’t.
Adopting an existing, well-known set of guidelines is often sufficient. What matters most is consistency, shared understanding, and having a checkable, documented reference the whole team can point to.
A practical starting point can be:
- MathWorks' MATLAB Coding Guidelines, or
- MonkeyProof Coding Standard for MATLAB
CC4M provides configuration presets for both.
If company- or project-specific conventions are required - for example naming rules for different entities - a custom configuration can be created, typically using one of the existing standards as a baseline.
2. Assess the Current State
Before changing anything, first understand where you stand.
At a minimum, assess compliance with the guidelines that have a higher severity level (for example level 5 or above). These are typically not stylistic issues, but indicators of functional or structural risk. When using the MonkeyProof Coding Standard for MATLAB, such violations may relate to complexity, excessive function/method length, incomplete if or switch statements, unsafe floating-point comparisons, and similar patterns.
The purpose of this step is not to judge the code, but to:
- Identify hotspots
- Understand risk concentration
- Establish a measurable baseline
This baseline allows you to track improvement over time and prevents discussions based purely on perception rather than evidence.
When You're Prepared to Start
3. Document and Style the Code
A surprisingly effective improvement strategy is simple:
Whenever you're already investigating a piece of code, improve its documentation and style.
While reading or debugging code:
- Add clarifying comments
- Improve naming of variables, functions, and classes
- Align formatting with your chosen style guidelines
The benefits are immediate. The next person opening that file, including your future self, will understand it faster and with more confidence.
Limit yourself to documentation and layout until you actually need to change behavior. Once functionality must change or a bug needs fixing, that is the moment to move on to refactoring.
How CC4M helps with Style
CC4M provides a wide range of checks related to layout, formatting, and naming conventions. These are grouped into two predefined configuration sets:
- Layout: Many of these checks support automatic fixes, making it possible to consistently reformat entire functions or even folders within minutes. This enables quick wins in readability and visual consistency without changing behavior.
- Naming: A comprehensive set of checks covering various naming conventions. Different entity types, such as variables, properties, and functions, can each follow their own identifier rules. When only updating the style of a specific function or method, it is often sufficient to apply naming rules to local variables only, since renaming other entities may affect external callers. The configuration also includes checks for iterator variables, constants, and variables that unintentionally shadow existing functions.
4. Refactor Safely
In line with the Boy Scout Rule, it is good practice to improve the code you are already touching when fixing a bug or implementing a change. When reading about refactoring you will often encounter terms such as code or software rot, code smell, and design smell. Spending a little time understanding these concepts can be very helpful, as they provide vocabulary and patterns for recognizing improvement opportunities.
A key best practice is to separate refactoring work from functional changes such as new features or bug fixes. This separation helps ensure that refactoring does not unintentionally alter behavior and allows you to validate changes using existing tests or known reference outputs.
For larger or more structural improvements, consider architectural refactoring steps such as:
- Grouping related functionality into packages or namespaces
- Introducing classes to encapsulate behavior and data
- Migrating large or loosely structured data containers into well-defined objects
Object-oriented design can often reduce deep function nesting, limit global state, and make both data flow and responsibilities clearer. The goal is not to redesign everything at once, but to gradually introduce structure where it provides immediate clarity and long-term maintainability.
How CC4M Helps Improving Functional Quality
Beyond style and layout, CC4M provides a broad set of checks and reports aimed at functional quality, completeness, and testability, in some cases even highlighting architectural concerns.
Key capabilities include:
- Analytical reports for complexity, dependencies, variable usage, and cell array assignments, helping to identify hotspots and risky constructs.
- Naming-convention checks for higher-level entities such as classes, properties, and structure field names, supporting clearer interfaces and more maintainable designs.
- Checks on local and nested functions, which can reveal excessive scoping or hidden dependencies.
- Interface-related checks, including:
- Maximum number of input and output arguments
- Proper use of arguments blocks and associated restrictions
- Detection and evaluation of structure usage in function interfaces
5. Automate Quality Checks and Monitor Them
A valuable practice in any development workflow is the design or code review (see the next section). At the same time, automate whatever can be automated. CI/CD systems are well suited for running static analysis, executing tests, and generating coverage reports. Most platforms also allow you to monitor trends over time, not just simple pass/fail outcomes, which helps teams see whether quality is improving or degrading.
MathWorks provides documentation and examples for integrating MATLAB testing and analysis into many commonly used CI/CD environments, making automation accessible even for smaller teams.
How CC4M Helps with Automation
CC4M provides a fully documented CLI (command line interface) that can be used directly or embedded into custom tooling. Through the CLI, both analysis and result processing can be integrated into virtually any workflow.
- CI/CD Integration: CC4M can function as a quality gate or as a reporting component within CI/CD pipelines and higher-level monitoring environments.
- Local Automation via Hooks: Using repository hooks, CC4M can also operate locally as an automated quality checkpoint before changes are committed. See the blog on Git hooks and CC4M.
6. Involve the Team
Code quality is a team responsibility. It constantly competes with deadlines, budgets, and delivery pressure, and without shared discipline, improvements rarely stick. Engaging the whole team is therefore essential for lasting success.
Practical ways to involve your team include:
- Ask which parts of the code feel most risky or “scary”
- Improve those areas incrementally as they come up in development
- Introduce code reviews, but keep them focused and efficient
A few good rules for reviews:
- Request full peer reviews only for code that already passes automated checks
- Otherwise, clearly define a limited scope (for example, architecture, interface design, or critical modules)
This approach respects your colleagues’ time while encouraging meaningful collaboration.
Finally, track and share progress: visible improvements motivate the team and reinforce the value of consistent quality efforts.
How CC4M Helps with Collaboration
Automated checks provide fast feedback and help developers learn and follow coding guidelines and best practices. Over time, this consistency in layout and naming conventions leads to more uniform, readable, and maintainable code.
By automating the repetitive and “boring” tasks, code reviews can focus on design, architecture, and functionality, fostering greater engagement and much more productive, insightful discussions among team members.
Conclusion
Improving a large MATLAB codebase by adopting coding guidelines does not require a complete rewrite, a project freeze, or heroic effort. What it does require is consistency and teamwork.
By focusing on incremental improvements, leveraging available tools, and embedding quality practices into everyday work, even the messiest codebase can become safer, clearer, and more maintainable — all without breaking existing functionality.
We’d love to hear from you! If you have feedback, suggestions, or questions, feel free to contact us.
- Van Gogh painting from WallpaperAccess
- Smoke photo by Mulyadi on Unspash
- Devops photo by Growtika on Unspash
- Team photo by Josh Calabrese on Unspash