Programming with style

Learning to read and speak English, French, Spanish, or any other language requires learning vocabulary, spelling, grammar rules, punctuation, idioms, and tools such as dictionaries and thesauri. Learning to write — and especially to write well — takes lots of practice, requires reading and dissecting lots of other writing samples, and involves a lifetime of learning and practicing various techniques, terms, and even styles. And each kind of writing has its own style and format: consider the difference between non-fiction, fiction, poetry, and technical reports (just to name a few). Many of these areas, especially those that are more formal, have standard styles and formats with rules that make it easier for readers to consume lots of documents. For example, the MLA Handbook documents in great detail the style and format rules for research papers, and its used in many secondary schools, colleges and universities.

Learning programming languages

In many ways, programming languages are very similar to written and spoken languages: they have their own grammar, terminology, vocabulary, punctuation, and idioms. Learning to read a programming language is much easier than learning to write, since writing code requires mastering many these skills. Learning to write code requires practice and dissecting of other people’s code. And, perhaps not surprisingly, each language has preferred styles and formats, and some even have style guides to help developers format their code in similar ways.

Why is style so important? When multiple people read or work on the same codebase, the formatting of the source code has a very big impact on how easy it is for people to read, understand, maintain, and express the intent of their logic. Code is already complicated enough, and using consistent formatting and style eliminates as much variation and unnecessary complexity as possible. Speaking from experience, it’s very easy to start working on a codebase when it looks like code you might write.

Java Style

 

Java has been for many years one of the most (if not the most) widely used programming languages. It’s also powerful enough that a lot of companies use Java as their primary programming language. But it is also relatively simple with a small number of straightforward concepts, making it a great language for students to start with. Many of our students’ high school programming classes use Java, and our team uses Java to program our robots (you can get a glimpse of our code by looking in our GitHub repositories). In fact, many FRC teams  and now FTC teams use Java to program their robots, too.

The Java Style Guidelines is the Java-equivalent of the non-fiction writer’s MLA Handbook. It outlines many rules for how to format your code, making it easier for multiple people to read, understand, and maintain. But the Java Style Guidelines were first written in 1999 (yikes!), and while it provides a good foundation, it hasn’t been updated and it hasn’t adapted to the best practices that Java developers have learned in the past 20 years. The de facto style standards used today by many Java projects no longer matches what’s described by the aging Java Style Guideline.

At long last the OpenJDK community has proposed updating the Java Style Guidelines to better reflect the conventions that most people are now using. And in true open source style, they’re looking for feedback from you (and everyone else).

Do you really have to learn all these rules? Well, yes and no. If you’re a Java programmer, then you really should learn to read and write code that follow these format and style rules: it will save you vast amounts of time when reading code written by others, which is something that you’ll do probably more than anything else. And, when you write code that follows the common conventions, and other developers will think your code more professional. But in truth, most Java development tools will automatically format the source code, so you just need to set up your tools to follow the project’s conventions. For example, FRC 4931 uses Eclipse, and our formatting preferences are already similar to these proposed guidelines.

So have a look at the OpenJDK’s proposal for an updated Java Style Guide. And if you don’t like one of the rules, give some feedback to the OpenJDK team.