Code Style: Formatting

Introduction

When people talk about Code Style they refer to their Naming Conventions, Code Structure…
What they tend to forget are the Formatting Guidelines. Something that’s not been taken serious enough in my opinion; but it’s one of the guidelines that I like to talk about.

With Formatting Guidelines, I mean the rules and guidelines that have been adopted in your team to format your code base files. When I hear people question my vision about these guidelines; that’s the moment when I’m certain that it’s INDEED important to adopt Formatting Guidelines for your team.

The reason people tend to question this, is because they don’t see the purpose and reason why these guidelines are important. I am convinced that Formatting in the topic of Code Style is important.

Formatting Basics

Formatting?

What do I mean with Formatting? Isn’t that just wasteful work? It doesn’t change my code behavior?
The first question I will discuss in this paragraph; and NO, it isn’t wasteful work; and NO, it doesn’t change your codes behavior.

What formatting means is the structure of your code. Just like adding an ENTER statement to start a new paragraph, or adding a trailing space after the point of your sentence.

Formatting is all about these little modifications in your code base. We developed a Formatting Guidelines document which captures our teams’ guidelines involving all the different ways we format our code. This document isn’t fixed but is dynamically formed and changes weekly by adding more and more verified ideas to format our code.

Formatting is about changing your code in a uniform way to make your intensions clear. Only a non-professional would ignore formatting and not use it in his/her daily practice.

Formatting Principles

One of the most important principles in Extreme Programming (XP) is Humanity. Maybe a simple principle at first but a very large portion of today’s literature doesn’t validate this simple fact:

“People develop software”
-Kent Beck

The Humanity together with Quality is for me the MOST important principles if you think about formatting in code style conventions. We as people develop software; we as people are reading this software daily; we as people are changing this software daily…

Wouldn’t it be more than normal that we create an environment where people feel safe to contribute, feel like they belong to the teams’ efforts and growth so they fully are being understood by everyone?

THAT’S what Humanity is all about. Formatting is about people. Formatting allows you to structure your code in a uniform way so that everyone can quickly spot what they are searching for. We, as developers, are reading more code than we write; so, with that in mind we should have our focus on the way people read code instead of just writing the code.

When I first heard about this statement, I was even more convinced that code should be: Simple, Clean, and Structured.

Formatting Patterns

The following patterns are just some basic ideas that I’d like to share with you. These aren’t all the patterns but I list them here to give you an idea to define your own patterns and come up with new ideas for your own.

Separate Concepts

It’s magical what just a single ENTER can do in code, but be careful where you use it. If you have a 10-line method and you place some ENTER here and there to increase Readability, that is a good thing, but maybe not the best solution.
Maybe you have the beginning of the Long Method Code Smell and have to refactor some with Extract Method Refactoring.

What I like to discuss are the other cases: the cases with where you have a method with a return value for example. Look at the following code snippet:

I could just have placed the “return new Attachment” statement with the two others, but instead I placed it on a separate line. Another example:

Here I have an ENTER after the Guard Clause; while I’ll just could have place the “UpdatePersonFromStore()” method a line up.

Both examples indicate the pattern of Separate Concepts. This patterns is about the separation of different concepts. The ENTER is the Separation in this context and the return/guard-clause are the Concepts.

The “return” statement in the first example is the actual Plot of the method. This plot is more important than the retrieval of the content type or location. It’s also a total different Concept, so we place it on a different line.

The second example with the if-statement is about time you spend reading. When there’s an exception being thrown, we won’t have to look at any other statements. So, we placed an ENTER after the exception statement.

These two examples are just a start for the practical implementation of the Separate Concepts pattern; but now you can find your own places to separate the concepts.

Conceptual Affinity

The second pattern I want to discuss is Conceptual Affinity. The relationships of elements of the same concept; that’s what this pattern means.

The practice is finding ways to place elements of the same concept as close as possible with each other.

We could just place the “SetLow(int)” method below the “Calculate()” method; but we didn’t do that because:

1. SetHigh and SetLow are method with the same Signature
2. SetHigh and SetLow are doing structurally the same action

With these two reasons, we can conclude that these two methods are more likely in the same Concept than the relationship with the “Calculate()” method.

A bit subtler is the following example. We could also have retrieved the one hour before we retrieved the current time; but to support the Concept of calculating the time from now with one hour, we have the retrieval logic in the same order as the formula.

This way the concept of calculating is related to the concept of retrieval and increases the Cleaniness and Simplicity of the code.

Try to switch the values and see for yourself that this way of writing is easier to follow.

Now it’s time to spot your concepts and the best solution. The last example of is on the edge of the refactoring Extract Method I think; if the calculation of the two values would become more complex, than that would be a good time to extract the two temporary variables to their own methods.

Newspaper Metaphor

The last pattern I will discuss with you is the Newspaper Metaphor (from the book Clean Code). This pattern talks about the global structure of your code files. The location of each element and the proper position.

When you write a class, try to hold this pattern in mind. Just like a newspaper, you place the Header and important items on the top, and place the Details and more concrete information at the bottom.

This will increase the readability of your code file; and you will spend less time searching the file.

Following structure could you use to define the order of the global elements:

1. Fields
2. Constructors
3. Properties
4. Public Methods

In each element, you could also define a structure for the visibility and place for example the Public Methods before the Private Methods.

Besides the global structure of elements is the Newspaper Metaphor useful for the flow of the code file. Just like a newspaper you must make sure that you can read your file from top to bottom without jumping (too much) back up. This is also called the Step-Down Rule.

Notice that this sequence is a standard convention of the Microsoft Guidelines and not an invented idea. Also, when writing in this structure always think of the relationship between components:
If a public method has several private methods which it delegates to, place those methods as close to the public method as possible. If you’re reading a headline in a newspaper and find it interesting, you want to read more of the details directly under the headline and not on a different page.

With this last pattern, you can start with searching for the perfect article in your code and make it worth the read.

Conclusion

When people don’t find it very interesting or don’t see the added-value of Formatting; they don’t think in people-terms but in terms of tasks. They’re Task-Minded and not People-Minded.

I hope with this short article about Formatting, you will also be/become People-Minded and use these peoples as your teams’ strength.

There’s a lot more patterns about Formatting which increases readability and supports Humanity; but I’m sure that, with this as starting point, you will find your own patterns that make YOU more comfortable. Try to make a Formatting Guidelines document for your team so everyone feels comfortable about the whole Formatting practice and everyone can make sure that everyone’s daily development work is just that little bit more restful and less annoying.

My mistake was to write a long document with all the possible approaches I could think of; but not everyone is so disciplined in adopting these patterns so try to limit yourself in a One-Page-Document (Example in Java) with maybe a class as example to show:

• How do you sort fields, members?
• How to write flow statements (return, break, continue, …)?
• Where do you place enters to increase readability?
• …

Codit is a company which primary focus is People so it’s only logical that we are paying attention to this practice of Formatting and making sure that everyone feels comfortable about reading code.

“People develop software”