Conventions In Software Development. Bring The Culture To Your Project

When you develop a custom software solution, you are guaranteed to face the problem of keeping it nicely structured and strictly ordered. We already mentioned the vital importance of this in one of our previous articles on the Complexity Problem. One of the first things you have to take into account when starting a project is Conventions.

In general, conventions are the documented or verbal agreement, which describes common work scenarios for developers and other experts involved in your project development. Conventions represent the organizational and technical framework for your development team functioning. In other words, conventions build strong traditions and standards for code writing, application and architecture design, communication, and other project aspects.

Developers and project management often ignore or underestimate the potential of development conventions. It happens for different reasons, and the most common is a lack of experience and discipline. In fact, conventions can bring significant value to your project development:

• Reduce the amount of project documentation. The generic rules you specify via conventions eliminate the routine of repeating the same documentation for each and every case.
• Simplify project understanding. In this sense, project development is like a board game: If every player in the room knows and follows the same rules - the gaming process is enjoyable and straightforward for all. Of course, the newcomers will require some help from you initially, but they will become the knowledgeable part of the team eventually.

With that said, let’s discover the types and levels of development conventions and figure out how to introduce them seamlessly. 

Convention Layers: Clean Project Structure On All Levels

We can divide the software development conventions into 3 levels:

• Code-level conventions;
• Solution-level conventions;
• Abstraction-level conventions.

As you may have noticed from the picture above, different convention levels associate with a developer's seniority level, and it happens for a reason. Let’s consider each level in detail to understand this correlation.

Code-Level Conventions

Code-level conventions are the most primitive. Developers discover those rules when they are only beginning to learn the development language. Project leaders can also modify or add new canonical rules for keeping the project code clean, auto-generating the documentation from the source code, personal preferences, or other reasons. Code-level conventions include but are not limited to the following:

• The Naming of your variables, objects, and other structures.
• Constants. How and where you create and use them, their definition formats.
• Comments. Rules for putting code explanations into a strict and readable format.
• Indents. The rules of the indentation that make it easy to read the code you create.
• Statements. The rules that allow or restrict developers from using short or alternative syntax in the code. 

As you can see, code-level conventions are entry-level (junior level) and don’t require strong employee expertise to create them. On the other hand, the incorrect decisions your team makes on this step can lead to significant expenses in the future. Changing the existing code-level conventions or introducing the new ones later means you need to change the existing codebase. This is unnecessarily expensive and takes a long time to implement.

Solution-Level Conventions

Solution-Level Conventions are more complex and require far more hands-on experience from the implementer. The complexity level these rules have is often comparable with the responsibility of the middle-level developer. Solution-level conventions usually include the following:

• Module structure. Dividing your product into isolated functional units makes the codebase easy to understand. You can always see functionality in each module.
• File structure. It may be complicated to navigate through countless project files in search of specific functions. This leads to spending hours and constantly switching between different files in your solution. High-quality conventions make the process fast and convenient.
• File naming. Similar to the naming in your source code, smart file naming conventions improve the file structure readability and simplify the search for some specific items. 

Solution-level conventions positively impact both the development and DevOps process performance. The strict and elegant structure of the sources of your project makes your build and deployment scripts tiny and lightweight. And this means cutting your expenses in the future.

Usually, introducing the solution-level conventions makes the project structure clearer and reduces the complexity level of the whole project. This speeds up your development process and saves your time and money in the future.

Abstraction-Level Conventions

This level is the most complex for understanding and only highest-level developers (senior-level) are suitable for creating those rules. Abstraction-level conventions aim to document the meaning of the project entities, their availability, and the proper way of using those.

Most developers only follow those rules and implement new features into the project based on the established framework. Here are the core components of the abstraction-level conventions:

• Abstraction entities. These rules form the entity definitions and their purpose in the whole processing algorithm.
• Abstractions areas. These rules define the project areas for using specific entities.
• Abstraction usage. These rules cover the relevant cases and reasons for using specific entities.

Frequently developers fail at following these conventions, and this happens for two main reasons. Firstly, developers may lack the relevant experience, strong fundamental knowledge, or time working with this specific project. Secondly, there may be existing low-quality conventions that make the project unclear and - therefore - lead to an incorrect understanding of how things should work.

The Challenges You May Face When Creating Conventions

As we have already discussed, the proper conventions can make your project significantly easier to understand, eliminate the waste of time, optimize your documentation, and - consequently - lead to saving the budget. Nevertheless, you should take convention development seriously.

Before introducing the new conventions to your project, consider the following points:

• You need a strong and very disciplined technical leader who has proven technical expertise and keeps everything in order. This person has to be able to come up with a clean solution and explain his thoughts to others in simple words. Unfortunately, the chance of randomly finding such a specialist is equal to the chance of finding the diamond on the street.
• You need to enforce the existing conventions. Having the rules that nobody follows is not going to get you anywhere good. Your internal team structure has to support training programs, onboarding for new developers, code review routine, and other activities aimed at supporting and enforcing conventions.
• The last but not least, DO NOT OVERUSE CONVENTIONS. Conventions are not the golden hummer. Too many conventions can significantly increase project complexity. Returning to the board game example we’ve provided above, too many rules make the game unplayable. And you want all the members to understand how to use the rules. The more complicated it gets, the harder it is to involve new players in your game. Moreover, too many rules mean it’s nearly impossible to enforce them all at the same time. 

The Bottom Line

Controlling the project complexity is far from a no-brainer. It requires motivation, proper attitude, and strong experience in the industry. If you have a revolutionary idea but lack the technical expertise, the best solution is involving the professionals.