Neatness Counts: A beginner’s guide to why style matters in programming
I’ve always been a person who’s valued creative expression, someone who colored outside the lines. I was never one to follow MLA format when writing essays in school, and in fact, gave up on using more than one case in my handwriting (I began to print in all uppercase in my Sophomore year in high school, before it seemed all shouty to everyone else with the advent of texting, and have retained the habit to this day). I loved the crazy, cut-and-paste style of William Burroughs novels. And yet, as a software developer, nothing irritates me more than poorly formatted, undocumented code. How did it come to this?
Easily, as it turns out.
You see, writing for entertainment, or even educational purposes is very
different from writing code; Unless you’re working solo on a project (and God
help you, if you are, you poor, brave soul), other devs are eventually going to
need to pore over your code, and they’re going to need to be able to understand what you’ve written. No matter how clear your code may appear to you, or how well it works, if you’re writing paragraph-length functions that run off the side of the page, you’re not going to gain many fans among your peers. If your variables are oddly-named and you’ve left your code undocumented, anyone maintaining your code is likely to get lost, spending hours or maybe even days trying to navigate the functions you’ve written. This can not only frustrate your team, but also increase the cost of developing new features and fixing bugs in valuable man-hours, which your business product team will eventually translate into real-world dollars. A nebulous legacy code-base is one of the top time-wasters on any long-running project, and writing code that is clean, easy-to-read, and most importantly, easily-maintainable, will go a long way to avoiding the mounting tech-debt that poorly-written code inevitably causes.
- Line-Length
In ye olden days of coding, punch-cards were limited to 80 characters per-line.
Even after terminals began to be used, screen-size was severely limited compared to what we’re used to today, so the 80-character limit imposed by punch-cards continued to be honored. However, with modern screens allowing upwards of 5K resolution, one might be tempted to take advantage of the entire screen width. Why is this a bad idea? Firstly, it’s common practice for many devs to keep more than one editor pane open on their screen, in order to perform side-by-side comparison while writing code. Exceeding the time-honored 80-char tradition often will force these devs to scroll side-to-side or wrap text in order to view the entire line. Limiting line-length also gives devs extra space to perform actions like git blamein-editor. However, these are merely matters of convenience, and the biggest reason for limiting your line-length is much more important. You see, typographical research into line readability tells us that the optimal line-length for human reading comprehension lies within the range of 60–75 characters, with comprehension severely dropping past that length. This is also the reason why magazines, newspapers, and even e-book readers will split their columns.
Although coding languages often set optimal line-lengths at different lengths,
many set their max-line-length at the traditional 80 characters. To paraphrase
Jack Sparrow, this is more of a guideline than an actual rule, and you’re usually safe to go even up to 100 characters, but exceeding the limit should be done sparingly, and not without good reason. Myself, I set two guides in my editors, one to 80 characters and one to 100, treating the space in-between as a sort of ‘danger-zone’, and if I find myself straying too far beyond the 80-character limit, if I can’t justify the extra length, I’ll take the extra time to
re-arrange my text into a more readable format. This even extends to non-code writing… even now, as I’m writing this article in a full-screen-width vim
window, I’m forcing myself to adhere to the same rules I set down for myself
while writing code, and have very few lines where I’m exceeding 80 characters, and only exceeding 100 when absolutely necessary (usually when defining linked text).
2. Method/Function Length
The reasons for method/function-length limits are related to the reasons one
would set line-length restrictions, insofar as the length of a function can
affect one’s comprehension while reading the code, but there’s also a technical reason. When defining a function, one wants to adhere to good design practices, and the single-responsibility principle states that a function should only be responsible for a single part of the functionality provided by your software. How does that translate to method-length? The longer your method/function is, the more likely additional functionality is creeping into that method, making it all the more difficult to debug and/or write proper unit tests for that method. What defines a manageable method/function length will vary from language to language; in javascript, many devs will set the max function-length between 16–25 lines, whereas ruby devs will more commonly stick to methods with a maximum of 10 lines (with some even
stating that your methods should be no more than 5 lines, max, and as a
primarily ruby developer, I often get the feeling when looking at javascript
functions that I’m reading a big collection of run-on sentences). When you begin to exceed your maximum method-length, it’s usually a good indicator that you should step back and put some serious consideration into refactoring. If you’ve written a function that you need to do any scrolling to read in its entirety, it’s definitely a sign you’re doing something wrong.
3. Class/File length
More related to the modularity of your code than anything else, an overly-long class or file-length is often an indicator that you’re attempting to stuff too
much functionality into your class. An overly long class can also make debugging and maintenance difficult, as you’ll find yourself scrolling all over the place to find the location of whatever specific line of code you’re attempting to change. The maximum file/class length will again vary between languages (with many java devs arguing that there is NO upper-limit to class length), however, another factor to take into consideration is your system limitations (or, more likely, your peers’ system limitations). A larger file will take longer to load into a code editor, and keeping many large files open can be taxing on certain systems. This becomes particularly important if there’s a chance you may end up editing code for your application from a remote machine. I like keeping my maximum file-size to around 200 lines, but ultimately, this metric is going to be up to your team to decide.
4. Indentation
If you want to start an argument in a large group of developers, there’s often
no better way than to bring up indentation. Wherever your team falls on the old “tabs vs. spaces” debate (I’m no exception here, if you say tabs, you are WRONG), a consistent indentation style is crucial to the legibility of your codebase. In certain languages (CoffeeScript and Python immediately come to mind), improper indentation will, in fact, render code unable to build or function. Again, the style of indentation you end up settling on will vary from language to language (and sometimes from project to project), but the most important thing to consider (at least, in languages whose functionality does not depend on a certain style) is consistency… inconsistent indentation makes it difficult to tell when a code-block begins or ends, and at the very least, tends to make your code look really sloppy. You and your team should decide early-on which indentation style to use, and stick to it, and if you’re joining a team with an existing codebase, discovering what indentation style your team uses should be one of the first tasks you undertake.
5. Whitespace
Have you ever read a block of text that just seemed to go on and on? Chances are your attention started to drift, and you may have even needed to go back and re-read segments of the paragraph, as new bits of information get pushed out of your fallible, non-computerized human memory. It’s common among all programming languages to separate functions with a single blank line; less commonly, blank lines are also used in many languages (such as Javascript) to break up code within functions into logical chunks. Whitespace should be used judiciously, however, as some languages will not compile properly with improper whitespace, while others will ignore it completely.
6. Documentation
Another hotly-debated topic amongst developers, many programmers (especially when fresh out of college) will argue that in-code doc-comments only serve to diminish code legibility, and that your functions should be ‘self-documenting’, or that ‘your tests should be your documentation’. While there is some truth in these statements, (and in fact, self-documenting code is something we should always strive for), the reality of the situation is that code which appears to be self-documenting and perfectly understandable to you, may be incredibly hard for the next dev to touch your code to comprehend. Additionally, your specs may not adequately describe your code, or may need to address so many edge-cases as to make comprehension of your code’s functionality far from easy. A well-written doc-comment in a format such as YARD for ruby, or JSDoc for javascript, can go a long way towards allowing other devs to understand your codes underlying purpose. I’ve worked on teams where this was not only recommended, but required, and would often be told to go back and document my code if I tried to submit a pull-request that omitted documentation. This is so important, that some editors, such as Microsoft Visual Studio, will actually help you out by adding in a doc-comment skeleton to your methods/functions by default. As necessary as
documentation is, overly-documented code can also be a problem, as yes, it will affect code legibility. Inline comments, as opposed to doc-comments, should be avoided… if you find it necessary to include such comments in your code to explain what you’ve done in a particular line or function call, it’s usually a sign that your code is becoming too convoluted, and again becoming a candidate for refactoring.
7. Function/Variable/Class Naming
With so many coding tutorials where we’re presented with variable names like
`foo` and `bar` (not to be confused with FUBAR, if you’ve read my previous
article on military acronyms applied to software development) you might be forgiven for thinking that variable naming doesn’t matter. You’d be wrong, but it’s be forgivable. The truth is that good variable naming is fundamental to writing good code. The reason boils down to the two things we’ve been talking about this entire article: legibility and comprehensibility. It’s really a no-brainer, when you think about it. The name of a variable, function, or class is essentially meta-data that’s telling the developer the objects’ purpose. Providing meaningful data when naming your variables and functions is absolutely essential, and it’s something you should take seriously. A name should not be overly dependent on abbreviations, yet should not be descriptive to the point where line-length begins to become an issue. Also, and this is one point even I struggle with, you should not make attempts at humor with your naming. All it takes is one dev who doesn’t get the reference to throw extra man-hours down the drain, as your maintainer struggles to understand that reference to an obscure 90’s movie that you and maybe a few
other members of your team might have found hilarious when you were writing it. Variable naming should tell a story, so it’s imperative that you tell the right story.
Final Notes: Tooling
I could honestly write an entire article on each of these seven points I’ve
covered here (and probably will), that’s how much I believe in the importance of a rigorous adherence to a well-defined style-guide while programming. As I once heard and have often repeated, one should always write code as if the next person to maintain it is one frustration away from snapping and going on a psychopathic rampage, and that person knows where you live. The good news is, you don’t always need to keep all this info in your head when you’re
writing your own code. There are plenty of automated tools available to help you stay on the right path to writing clean, maintainable code, and to do them
justice, they’ll most likely be getting their own articles as well. For ruby, I recommend rubocop for code-style linting, and YARD for documentation, and for JS, esLint and JSDoc… all of which can be configured to best suit your teams’ chosen code-style, as well as run from your editor of choice and on whichever CI platform you run. Beyond that, there are code-quality linters, which analyze your code using various metrics to help you eliminate code-smells that go beyond mere stylistic issues, but those are also a story for another day. What I hope to have given you today is a starting-point upon which to develop your own appreciation for clean, well-styled, easily understood code, and hope you’ll take the beginnings I’ve given you to build up a well-polished code-style of your own.
