Packetizer Logo
 

Writing Code for the Next Person

By: Paul E. Jones

Code Style

Selecting a Style

If there is one topic that can start a debate more than any other in a development team, it is code style. Most teams have a preference, and some companies even publicly document their code style guides for the world to see. I applaud the companies that do publish theirs, as it allows for teams to learn from each other.

Among some of the well-known style guides are the following. This isn't intended to be an exhaustive list, but they represent the ones I encounter most frequently in my professional work.

Which style a team chooses to use doesn't matter so much (though I have my preferences I will share below), but what is important for productivity is to agree on a style and use it consistently. Doing so can improve productivity, as the layout becomes familiar to each person on the team.

My Personal Preference

My personal preference — and also largely adopted by Microsoft — is the Allman style. It wasn't always like that, though. When I started out my career, I wrote C code using the K&R style. As time passed — and perhaps influenced by Microsoft and other companies writing Allman style — I grew rather fond of it.

With K&R (which is also substantially adopted by Rust), the opening braces appear at the end of lines. The negative side effect of that is that one wastes time locating matching braces. While some code editors can help highlight matching braces, having them align vertically makes it much faster to see code blocks. Plus, the additional white space makes it easier to read. This gets into accessibility considerations I'll discuss next.

In addition to brace placement, I've adopted the style of PascalCase for function names; snake_case for formal function parameters, local variables, and class member variables; and Upper_Snake_Case for class member constants or global constants. For indentation, I use four spaces.

Accessibility Considerations

In recent years, there has been an increased emphasis on accessibility. This includes everything from parking spaces to sidewalks to web sites. However, accessibility is often not considered by developers when choosing a coding style, yet it's important and should not be ignored.

Google and Mozilla are two companies whose coding style guidelines introduce certain accessibility challenges.

Part of the accessibility issues stem from the use of K&R, which as I noted in the previous section, introduce more challenges for people to locate the start and end of code blocks. I can hear those proponents now saying, "No, it doesn't!" It, indeed, does for some people who have certain visual impairments like hyperopia or presbyopia.

Another issue is indentation. Both Google and Mozilla specify the use of two-space indentations. Years ago, the industry standard used to be a tab character, which was defined to be eight character positions on a fixed-width display. As time progressed, the norm changed to four character positions. That is still the style used by Microsoft and probably most programmers today. However, Google and Mozilla decided to use two. This presents challenges for certain people, including visual impairment and dyslexia. The white space helps to create a visual separation, whereas two spaces can become almost invisible for some. It simply makes it harder for some people rapidly to identify code blocks.

Tabs vs. Spaces

Way back at the beginning — long before I or most of you reading this were born — tab characters were used as a means of indenting code on the screen. The reason is that a tab character takes one byte of memory, whereas each space takes a byte of memory. The tab was defined as indenting eight character positions, so using spaces to indent vs. a single tab character was considered to be a pragmatic choice in order to preserve previous storage and memory.

As the years passed, people began to transition from using the tab character to using spaces. As mentioned above, the default indentation width moved from eight character positions to four almost universally. For a while, though, there were some who firmly clung to the use of the tab character even though there really was no reason. After all, storage space and RAM became relatively cheap. In fact, the code is usually insignificant in size relative to a computer's storage or RAM.

I still encounter code from time-to-time using tabs, but the practice needs to end. One of the really annoying thing about code with tabs in it is when somebody starts working on that code without realizing it used tabs. It results in an absolute mess. Fortunately, tools like vim can make it trivial to remove or add tabs, but at this point there really is no good reason to use tabs. So don't, unless the particular language calls for it (some still do).

Column Width

One of the things I felt that our industry had outgrown long ago was the 80-character column width. As I am sure everyone reading this knows, computer screens were introduced with 80 columns due to the fact that punched cards used 80 columns. Programmers just got used to 80 columns as the default width.

Microsoft is one of the few who (reportedly) moved away from the 80-column standard to 120 columns as a line width. In my opinion, that made sense. After all, virtually everyone today either writes code via a GUI code editor or uses an SSH window that can be easily resized to be much wider than 80 columns.

I asked my (then) development team about making a transition away from the long-held 80-column standard. Some were favorable to the idea, but I got resistance from two individuals who made several compelling arguments for sticking with 80-column line widths.

  1. Using an 80-column width allows one to place two code windows side-by-side on a laptop screen, which makes it easier to compare code or to borrow snippets from the other code window.
  2. Using an 80-columns width makes it easier to use GitHub when reviewing code in a pull request, as once can more easily place the diffs side-by-side on the screen.
  3. It is generally easier for humans to scan a narrower visual field when reading. Thus, if using 80 columns one can see more of the code without having to move one's head left and right to read the code.

While that last argument likely has merit to it, a counterargument is that forcing the 80-column line width limit actually results more line wrapping in modern languages. Wrapping lines can cause one to read code more slowly. Since most code would likely still fit within the historical 80-columns, there may not be so much of a need to look left and right.

So while I do have a preference for lifting the 80-column limit, there seems to be compelling arguments as to why it should be retained. And, of course, most of the development community seems to be content with the current restriction.

Function Length

Perhaps one of the best code style recommendations I received in my career was to never write a function that was longer than 100 lines long. The argument was that, if you need more than 100 lines, then you can probably find a way to restructure that function into a few, smaller functions that are easier to read, easier to maintain, and less likely to contain bugs. Unit testing is also simplified and more narrowly scoped.

There are a few exceptions to this rule:

  • If the code is modestly over the limit, fine. Don't break a short function only for the goal of keeping it within 100 lines.
  • If breaking the code into pieces actually reduces readability, then allow it to be longer. This is generally true in functions that perform a simple task, but just contain a number of non-breakable steps.
  • If breaking the code apart has a serious, negative impact on performance, then leave it as a unit.