Connect the Braces
A game to help visualize effects of brace placement style in Java
The Objective is to be Objective
Several years ago, I came up with a creative approach to help establish and agree upon coding style with a new team I was working on. We were in the beginning stages of coding on a new project using the Java programming language. I requested that we decide and agree upon consistent code style guidelines as a team, up front. I knew I needed to come up with an objective and creative argument to address one of the contentious code style debates in Java — where to place the curly braces.
Choosing Creativity over Conflict
Swimming against the tide of “but everyone else does it this way” is hard. It’s even harder when a highly respected search company stamps their seal of approval on a particular Java coding style.
To help me present an objective argument for a particular brace placement style, I created a game I called “Connect the Braces”. I took code from two example classes I created and pasted them in a Powerpoint deck and literally drew lines on top of the code to connect the beginning and ending braces. The game was inspired from one of my favorite childhood games — “Connect the Dots”.
The great thing about “Connect the Dots” is is the rules are simple, and almost everyone has played the game in school. “Connect the Braces” is also very simple. Just connect the beginning and ending braces of each code scope by drawing a line between them. Easy.
I presented the game to the team, and after I was done, no one responded “but everyone else does it this way”. This confirmed that at least one team responded well to a creative argument about brace placement style.
Automating the game
I told my friend Vladimir Zakharov (Vlad) about this game, and how it effectively defused what I had previously experienced as an incendiary debate. I asked Vlad if he could write some Java code to visualize the game I described to him. Vlad is better at visual programming than I am, so I knew he would complete the code faster than I would.
Vlad did something even better than just connecting the braces in a source file. He also colored blocks of code in green highlight. This has the added benefit of visually highlighting whitespace.
The images in the following section were generated using Vlad’s automated version of “Connect the Braces” on actual code from the Eclipse Collections Kata.
Warning! Game on!
The following images are graphic. Some developers may find them disturbing. Actual source code was used in the creation of the following visuals. Any images that cannot be unseen after scrolling beyond this text is the sole responsibility of the person scrolling, not the author. Any fruit or pet emojis that were harmed during the two “Connect the Braces” rounds were the result of code style choices, not the author. Choose wisely. You have been warned!
Round One: Fruit Enum
Round Two: PetType Enum
Choosing Clarity over Clutter
I know I probably just waded into a raging river filled with hungry piranha while wearing a pair of swim trunks made out of steak. I am not looking to convince everyone that a particular brace placement style is the “one true style”. There is definitely a style I prefer when I write code, and I have to argue for it on every project that I work on. I find that when I present my argument using this game, we can have a healthy discussion about the importance of aesthetics, white space, and visual tracking for code scanning and readability.
I choose clarity over clutter. Signal over noise. I choose the style on the right.
To quote my friend Vlad:
When I read code, I usually want to see either the “what”, e.g., what are the responsibilities of the this class, what is this method’s contract, what is the condition to trigger this branch — or the “how”, e.g., how does this method do what it does, what happens if I follow this branch, and so on. Having the whats and the hows visually segregated helps me scan the code and focus my attention on what matters at the time.
The vertical brace formatting style has a natural effect of cleanly separating the “what” from the “how” by introducing whitespace between signature (class and method definitions) and implementation (variables and code). The beginning and end braces are always in the same horizontal location, with variability based consistently on the depth of nested scopes (e.g. control statements like if, for and while). You expect to see the base of a pyramid shape with the braces, so can safely ignore where they are, because you know where they are. This style is easy to implement automatic formatting in your IDE and and enforce in a CheckStyle build.
I have been swimming against the tide by using this brace formatting style in Java for over 20 years. To developers who have to read or work in the code bases that are formatted using the vertical brace placement style because of me, I have something to say.
You’re welcome!
An Exception to the Rule
I choose a different brace placement style when creating Powerpoint slides or text for a book with Java code. In these two print media only, I almost always choose the style that favors fewer lines of code. Breaking code across pages is undesirable. This is a tradeoff that is made due to limits on available vertical space. This imposed limit does not exist in code you are reading in your IDE or in a browser reading source from a VCS like GitHub or GitLab where vertical scrolling works just fine.
Seven Ineffective Coding Habits of Many Programmers
A few months after I created the “Connect the Braces” game, I came across an amazing talk from Kevlin Henney who presents a great argument for a particular brace placement style, among many other great points he makes in the talk about coding style.
No spoilers. I highly recommend watching this talk. Warning, this talk may be a constructive disruption to your current coding style.
A Call to Action on Java Code Style
We are leaving billions of lines of Java source code in version control systems to be maintained by our future selves and future generations of developers. Code style has a direct and subtle impact on clarity and readability. Not everyone reads code at the same speed. There may be accessibility challenges that you should discuss and consider as a team. Everyone should be able to parse code eventually by reading it line by line, regardless of style. If we can spend fewer cycles separating the what from the how and finding code we are looking for, it would be a good thing.
Here are my rules for building an acceptable coding style on a team.
- Have discussions with your team about code style guidelines.
- Apply consistent code style guidelines in your project using auto-formatting rules encoded and customized in your favorite IDE.
- Run an automated continuous build that will break on inconsistent code style commits (e.g. CheckStyle).
- Publish your code style guidelines in your project VCS.
- Have the courage and take the time to evolve your code style guidelines when you discover or learn something new.
This blog focused on only one aspect of code style — brace placement. There are many others code style aspects to consider, and Kevlin does a great job of explaining some of them in his talk. I highly recommend watching Kevlin’s talk, “Seven Ineffective Coding Habits of Many Programmers”, that I linked above. I recommend discussing and agreeing as a team how you will address the long term readability properties of your code base. Do not just adopt someone else’s code style because it is convenient and readily available.
Feel free to use the Connect the Braces game to help facilitate rational and objective discussions about code style, especially as it applies to discussions around brace placement style in Java. If you like this style and want to see the the code style settings that we have used for in IntelliJ IDEA for Eclipse Collections for the past seven years, they are checked into GitHub here.
Enjoy!
I am the creator of and a Committer for the Eclipse Collections OSS project which is managed at the Eclipse Foundation. Eclipse Collections is open for contributions.
