When it comes down to coding styles, most choices are pretty arbitrary and depend on personal preference. Yes, even if tab width changes between editors, and spaces tend to be more precise. If there were such a thing as developer team anthropology, style guidelines would probably be a major part of it.
In this post we will highlight formatting guidelines and different Java coding styles in companies like Google, Twitter, Mozilla, the Java standard, and our own teams at Harness.
(Whether you use tabs or spaces, it’s what you write after them that counts. Code quality is crucial, which is why Harness analyzes your code at runtime to give you actionable insight about all errors and slowdowns – even those that don’t end up in the logs.)
Readability is the main consideration here. It’s almost certain that you will not be the only person to read the code that you write. And the best thing you can do for the next person who reads your code is to stick to conventions.
A consistent style of writing not only helps create good looking code, but also makes it easier to understand. The twitter guidelines specify one exception and we tend to agree, “if the more ‘readable’ variant comes with perils or pitfalls, readability may be sacrificed”.
Let’s see what they have in store.
First, we need to get this off our chests before proceeding. There’s a clear preference for spaces over tabs in the style guides. We’ll not go into pros and cons here and just share the findings:
Data from Github suggests that around 10-33% of the Java repositories prefer tabs, and the majority use spaces in different formations, preferring 4 spaces over 2. There’s actually a pretty nice module for running this analysis (comparing different languages). BTW, peeking over to other JVM languages like Scala and Clojure, we see almost 100% 2 spaces.
Considering a larger dataset that covered individual commits gave us different results (The convention analysis project, one of the Github data challenge winners), but we can estimate it to be somewhere in-between probably closer to 10%.
Sometimes lines of Java code tend to get long, and the style guides set conventions on when is it appropriate to break or wrap. The general convention is around 80-100 max length
Of course, apart from natural breaks after semicolons, line breaks are used not only when lines get too long but also for logic separation. The general convention is to break after commas, before operators, and use a hint of common sense.
Here’s an example from twitter’s style guide that makes good use of this concept:
This helps separate statements and create a logic where each line of code represents a contained / “atomic” operation. The style guides tend to agree here.
Blank lines also have an important role in the mix, separating logical blocks. The Java standard style guide also has a reference to double line breaks, separating interface and implementation.
Wide agreement across all style guides. FirstLetterUpperCase for class names camelCase for method and variable names, all lower case package names and ALL_CAPS for final static constants.
A common exception for this would be the logger, which we usually define as:
private static final Logger logger = LoggerFactory.getLogger(Class.class);
Twitter’s guideline adds another interesting style of including units in variable names:
Exceptions are a thorny issue. Recently we’ve covered a research that looked into over 600,000 projects on Github and Sourceforge and uncovered some grim truths about non standard use of exceptions. Google’s and Twitter’s style guides reference the infamous empty catch blocks:
Moreover, another guideline we recommend to at least try to keep is making sure your exceptions are actionable, and avoid control flow exceptions. The amount of noise so called “normal” exceptions cause in a production environment is terrifying.
The current state of exceptions and error handling, relying mostly on log files to get to their root cause in production, is our main motivation behind building Harness. If you haven’t already, check it out! We’d love to hear what you think.
Even when they’re not necessary, parentheses can help improve readability. With compound predicates, it’s common to use parentheses for clarity, even when the order of execution is obvious. For example:
So what do the style guides say about grouping parentheses?
When dealing with curly braces, all style guides examined support breaking after the opening brace.
One guideline that we keep and didn’t find in any of the style guides is not to keep any “brains” inside constructors (so they’re safe from zombies – but not from weak jokes apparently).
If we need to create an object and do some heavy duty operations to build it, we use a creator method instead. For example:
There are many more style guidelines that we didn’t cover in this post to avoid making this an exhaustive list, and they’re all available in the original docs linked at the beginning of the post. Readability is a major factor in keeping your code error-free, and… it just feels right to keep these OCD senses from tingling.
What are some of the unique guidelines/quirks that you follow? Does your company/team use a style guide of your own?
Enjoyed reading this blog post or have questions or feedback?
Share your thoughts by creating a new topic in the Harness community forum.