CTO Review of "Building Maintainable Software"

Being involved in the development of an Open Source platform for the last decade, software quality is a topic I am confronted with on a regular basis.

Maintainability (how easily a system can be modified) is one characteristic of software quality. Performance (how fast a system produces its output) is another.

Software quality is a vast topic and you can find a lot of valuable articles on the internet. So why a new article about software quality and why a focus on maintainability? Well the thing is that my team is currently facing challenges regarding team growth.

We are hiring more developers and many questions arise regarding integrating them in the team:

• How do we organize people in small teams (instead of one big team)?
  We have tried having a single team of more than 12 people in the past, however we did not like it. We feel more comfortable and efficient with teams of 2 to 6 people.
• How do we adapt the software architecture to match the new team organization?
  I strongly believe that the software architecture is a mirror of the teams’ organization. Hence the importance, when changing the team structure, of identifying the potential impacts on the software architecture and the other way around. This line of thinking is based on Conway’s law:

Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization’s communication structure.

— Melvin E. Conway

• How will new team members ramp-up on existing code?
  Our code base has grown to become quite large over the years. Of course we took special care to isolate services, modules and components in dedicated code bases. But still, we are building a platform with a large functional scope; our code bases are pretty large too.
• How do we keep the platform maintainable over time with those organizational & architectural changes?
  This is the question I wanted to elaborate on today.

I do not claim to have the answers on my own, that is why this is a topic I discuss with developers, other CTOs, and why I read articles and books about it!

Below are my takeaways from the book Building Maintainable Software: Ten Guidelines for future proof code, by Joost Visser.

The 10 Guidelines to follow when developers want to build a maintainable software.

Note: Software quality requires a lot of discipline and a clear set of priorities. That is why having rather simple guidelines that are easy to implement is very important for developers.

1. Write short units of code
2. Write simple units of code
3. Write code once
4. Keep unit interfaces small
5. Separate concerns in modules
6. Couple architecture components loosely
7. Keep architecture components balanced
8. Keep your code base small
9. Automate development pipeline and tests
10. Write clean code

My team members and I are already familiar with most of these guidelines. Guidelines 1, 3, 4, 5, 6, 9 and 10 are already in our daily routines (even if we still have room for improvement).

I must confess that we do not talk about guidelines 2, 7 and 8 often enough. But now that I am aware of this, we will definitely discuss these topics as a team and identify what actions we want to take and prioritize them.

In any case guidelines 1 and 2 are the foundation and should never be overlooked. Whenever a developer identifies any violation in the code base, he/she should apply the Boy Scout rule: leave the code cleaner than you found it. This is where refactoring techniques are handy.

Refactoring techniques every team member must know to make small improvements in code maintainability, when applying guidelines.

Extract Method

The Extract Method refactoring lets you take a code fragment that can be grouped together, move it into a separated method and replace the old code with call to the method. It is very handy to reduce the size of a method by extracting a new method leaving the code base with 2 smaller methods.

How to do it with IntelliJ:

1. Select a code fragment you want to extract to a method.
2. Press Ctrl+Alt+M or from the main menu, select Refactor | Extract | Method.
3. In the dialog that opens, configure a method options, such as visibility, parameters, and so on. You can also change a name of the method if you need.
4. Click Refactor.

extract method

Replace method with Method Object

The Extract Method Object refactoring moves method into a new class, converting all the local variables to its fields, allowing you to decompose the method into other methods on the same object. It is an alternative to the Extract method, and can be used when you have multiple return values in an extracted method.

How to do it with IntelliJ:

1. Select a code fragment that you want to extract into a class.
2. From the main menu, select:
   Refactor | Extract | Method Object
3. In the dialog that opens, specify the name of a new class, method and parameter options.
4. Preview your changes and click OK.

extract method object

Extract Parameter Object

The Extract Parameter Object refactoring lets you select a set of parameters to a method, and either create a wrapper class for those parameters, or use an existing compatible wrapper class. All calls to the method selected will have their parameters appropriately wrapped, and all usages of the wrapped parameter will be replaced by the appropriate calls on the newly created parameter class.

How to do it with IntelliJ:

1. Select a code fragment that you want to extract into a class.
2. From the main menu, select:
   Refactor | Extract | Parameter Object
3. In the dialog that opens, specify the name of a new class, method and parameter options.
4. Preview your changes and click OK.

Extract parameter object

Better than refactoring, writing clean code from the start! I know it is easier said than done.

The good news is that modern IDE have validation tools to search for code smells. In IntelliJ for instance you should try to activate the Java inspections to enforce the above guidelines.

Java inspection

What about you? How do you manage mainainability in your projects?