As members of the BioSistemika software development team, we always strive to deliver code of the highest level of quality. Good code quality is rightfully seen as one of the keys to the success of any software development project.
One key aspect of writing high-quality code is maintaining correct and consistent styling and formatting. When applied correctly, these practices greatly enhance the readability and maintainability of your code. In this post, we’ll explore the topic in more detail and share practical guidance on how thoughtful styling and formatting can help you improve code quality.
What is code style and code formatting?
Simply put, coding style refers to a set of rules or guidelines that define how our code should look. While opinions on what makes a good coding style can vary, most styles share common elements.
We’re talking about code formatting – it covers the visual structure of code, such as layout, indentation, and the use of whitespace, as well as software capitalization, naming conventions, and spelling rules for identifiers, functions, and variables. Some of these rules are often specific to a particular programming language or language family.
For example, in C#, there are style rules that define how we initialize objects and variables, when and how we use lambda expressions, or when we apply extension methods, and so on.
Image 1: Defining style and formatting guidelines is important (Source: Wikidave)
Why is unifying code styles important?
The quality of a well-written code lies not only in how it works, but also in how it looks. At first glance, proper code formatting might seem very trivial or unnecessary. After all, the software that our code interacts with doesn’t really care about its appearance, but this is not the case with other co-developers. They might need to read our code, understand it, or even edit or collaborate on it. In this aspect, proper and unified code styling can make a significant difference. Here are some key benefits of maintaining a consistent code style:
- Improved readability – Consistent formatting makes the code easier to read, and consequently, easier to understand. When we’re reading a block of code that’s using an already familiar code style and formatting, it helps our brain focus on the most important part – understanding the code and its functionality.
- Improved collaboration – Following the same formatting standards helps teams work together more efficiently. Developers can read, review, and contribute to each other’s code without adjusting to individual quirks or habits.
- Improved maintainability – Readable and consistent code is easier to debug, modify, and review. Code reviews become faster since reviewers can focus on functionality instead of style-related issues. Additionally, using consistent formatting also considerably lowers the number of merging conflicts.
Unifying the development team’s coding styles should in no way be an attempt at making all code look like it was written by one person. The equivalent of this would be asking a team to collaborate on writing a 100-page paper with the same writing style. While they will most likely use the same paper size, language, font, and structure, it will still be apparent that the paper is the work of multiple people. The goal is consistency, not uniformity.
Unifying and enforcing a consistent code formatting style at BioSistemika
Below, we outline the steps needed to effectively research, prepare, and implement unified code styling guidelines and rules. We also explain how we at BioSistemika ensure consistent code styling across our development teams and share the reasoning behind our choice of specific tools.
Introducing unified code styling guidelines and rules can be a long-term, multi-stage project. That is why it’s best to begin where the impact will be most significant. In our case, we started this process with a part of our development team working on software projects using .NET, one of the widely used software development frameworks in the company. To be able to name the tools used and talk about specifics, we’ll use this stage as an example throughout the rest of the blog.
First, it’s important to define clear goals, limitations, and requirements to guide us through this type of project. In our case, we prioritized the following factors:
- Define coding style, formatting conventions, and guidelines that result in an aesthetic and readable code. These guidelines should also be ones that most developers can agree on and comfortably apply.
- Find a reliable way to verify that all newly written code is styled and formatted according to our guidelines.
- Find a way to automatically format and style code, to reduce manual work and human error.
- Minimize disruption and interference with the developer’s workflow. Integrate style checks into the existing development process to run quietly in the background. This helps maintain productivity and encourages developer buy-in.
- Use tools that are easy to integrate into both new and existing .NET projects. Whenever possible, prefer CLI-based solutions that can also be included in CI/CD pipelines. Avoid tools tied to a specific IDE or version to keep the system future-proof and adaptable to different workflows.
To set up styling and formatting rules and guidelines, we’re using a .editorconfig file. This configuration file is supported by a wide range of IDEs across different platforms and frameworks, including those most commonly used by our own .NET development team – Microsoft Visual Studio and JetBrains Rider. A significant advantage of this kind of setup is that both mentioned IDEs offer us an option to format code out of the box automatically. They also support a convenient GUI for editing .editorconfig-based formatting rules and guidelines.
In our case, we’ve placed this file inside the root of each .NET project file structure, and in some specific cases, we overrode some of these style rules by placing another .editorconfig file in an inner directory. This approach ensures that the vast majority of rules remain synchronized across all the .NET projects.
We can play around with many different options, allowing us to personalize the rules to our team’s needs. Configuring and optimizing the rules will most likely be a time-consuming and effort-demanding process. It’s unlikely that everything will be perfectly configured on the first try, so we should expect to revisit and refine the setup multiple times.
In each iteration, the selected options should be tested, evaluated, and adjusted, re-tested if needed. It’s best to involve as many members of the development team as possible during testing and evaluation. This not only keeps everyone informed about the changes but also brings diverse perspectives and feedback to the process.
We might also encounter some rules that conflict with one another or some rules that do not work as expected in certain situations. Throughout this process, clear communication among developers is essential. After several iterations, the team should arrive at a well-balanced set of rules that work effectively for most.
The most important aspects of the guidelines that we define in the .editorconfig file include:
- Indentation – Helps the person reading the code clearly and quickly see the code’s structure and the hierarchy of code elements.
- Spacing – By defining and limiting the allowed number of line breaks and spaces between different code elements, we ensure that the code remains consistent, tidy, and easy to read.
- Casing – Code must use appropriate casing. For example, in our setup, functions, namespaces, and class names start with a capital letter, while private properties begin with an underscore followed by lowercase letters. When defining casing rules, we can use the existing types (camelCase, PascalCase, kebab-case, etc.).
- Code blocks – Define how code blocks should be structured and formatted.
- Naming and declaration rules – Set clear standards for naming and declaring variables, interfaces, classes, and namespaces.
Image 2: Just a quick glance at the code should give us an idea of its structure and hierarchy (Source: ActiveState)
With all of this in place, all developers using IDEs that support automatic formatting and are working on the project that includes our customized .editorconfig will have their code made more consistent and styled similarly. These IDEs will automatically format code during writing, as well as underline and warn the developers about any possible mismatches between existing code and added styling guidelines.
We’ve configured the .editorconfig so that in most cases, mismatches between written code and formatting rules will result in the IDE displaying a warning. However, the code will still compile, even if it doesn’t fully comply with the styling guidelines. While using IDEs’ auto-formatting functionality is recommended, it is not mandatory, especially for code that is still in progress. Some developers might also prefer to use other IDEs that do not support automatic styling.
Because of this, we need to verify that all completed code blocks — meaning code that is committed, pushed to a remote server, and later merged into the parent branch — fully comply with our styling guidelines. There should be no exceptions at this stage.
We explored several approaches to addressing this requirement. One option we evaluated was adding a .git pre-commit hook that would scan all the changed code files in the commit. This hook would use the dotnet format tool, which is already a part of .NET 6 SDK or newer versions. By using the configured .editorconfig file, this tool will automatically edit these files and make them compliant with the formatting guidelines. However, this approach had a major drawback — developers had no visibility or control over what parts of their code were modified, as all changes happened in the background. Because of this lack of transparency, we ultimately decided not to pursue this method.
As an alternative approach that would bring us to the same result, we introduced an additional CI/CD job/action/step that automatically triggers after each commit, alongside the existing compile and test jobs. Again, we’re taking advantage of the already mentioned dotnet format tool. By using the project’s .editorconfig file and format tool’s –verify-no-changes parameter, we’re able to check for code style compliance and fail the job if any formatting issues are discovered in the newly committed code. The tool returns a convenient report with a list of lines of code that do not follow the guidelines and suggests how to correct them to make them compliant with the configured style. Until all the formatting issues are addressed, the commit cannot be merged back into the parent branch.
By using the format tool’s –include parameter, we can limit the check to only those files that have been modified in a specific merge request. This ensures that all the newly added code styles will match our guidelines, but we won’t be checking formatting guideline compliance for the whole codebase, as this could be too disruptive. This approach allows us to check and possibly correct the existing code’s formatting in multiple smaller and more manageable chunks.
Image 3: Preventing the merge of any non-guidelines-compliant code (Source: The One Brief)
With all these steps in place, we successfully met all the initial goals of our internal project, which was to implement and enforce unified code styling and formatting guidelines.
Are you planning a new software development project for life sciences or medical device industry?
Learn more about our expertise.
Summary
In this blog post, we explored the concepts of code style and code formatting, along with the benefits of applying consistent styling guidelines in the software development process. Using a .NET project as an example, we demonstrated one possible approach to introducing, automating, and enforcing proper code formatting.
We hope this overview provides useful insights and inspiration for teams looking to implement similar tools and practices — ultimately helping them improve both the readability and quality of their code.
