On Style

Embed from Getty Images

I’m pretty sure there’s a lot more to life than being really, really, ridiculously good looking. And I plan on finding out what that is.

– Derek Zoolander, Zoolander (2001)

Consulting exposes you to so many codebases and so many coding styles. This is especially the case when it comes to coding in JavaScript, a language so expressive and fluid that there are so many ways to accomplish the same piece of functionality.

JavaScript style guides abound. In this post, I would like to discuss some of the benefits of using or implementing your own style guide, as well as a few things I’ve learned traversing the bardos of development. While some of these insights are specific to coding in JS, most extend to coding in general.

Don’t rock the boat (without a chat).

Consultant or not, a good developer is a ninja in the codebase. (This is one of the most tired metaphors in development, but I could think of no better term, aside from secret agent). Do a good job and make it seem like you were never there.

Don’t use seven words when four will do. Don’t shift your weight, look always at your mark but don’t stare, be specific but not memorable, be funny but don’t make him laugh. He’s got to like you then forget you the moment you’ve left his side.

-Rusty Ryan, Ocean’s Eleven (2001)

The best code reads as if it was written by a single person. That single person is the team. As an engineer, your aim should never be to write a piece of code so slick that the code around it cowers in unworthiness. Sure, it can and should be awesome, but it should remain in context. Try to mimic syntax and architecture choices. As a fellow team member, you always want to strive to improve the code, but make it seem like they wrote it themselves.

If the code is so horrific, organize a team chat before you decide to change how everything is done. A style guide that everyone references and adheres to should be the goal of that chat. Linting is also your friend. JSHint or JSLint can be customized to your team’s development standards and be included as part of the build process.

Bad code costs more than money.

Sloppily written code slows down development. As a developer, most of your time is spent reading other people’s code. Inconsistent spacing and syntax, aside from questionable architecture, is slower to read and comprehend and slower to debug. Onboarding new team members takes longer. The more time spent reading and debugging rather than coding just makes development cost more. Frustrating code makes people grumpy. We don’t want to work with grumps.

Don’t be too clever.

I’ve spent some enjoyable evenings working through coding challenges on Codewars. One thing I’ve noticed, however, is that the top rated solutions to challenges are always obtuse one-liners. They are very clever, blocks of code that read like haikus. They’re beautiful. Still, if you came across it in your codebase, would you understand what the code was doing right away? Maybe it would take 10 seconds until comprehension versus an instant. Over time this adds up. As minification is a standard part of development, brevity at the cost of readability doesn’t make much sense.

Write to be read.

Keep it simple. Like with prose, the best code is simple and clear.

Annotations and comments should be minimal. For annotations, descriptions should be simple, yet beefy enough that if turned into actual documentation, the reader would get the point easily without referencing the body of code itself. Comments shouldn’t be too necessary. If you find yourself writing lengthy comments explaining your code, it needs refactoring.

Descriptive variable and method names help decrease the need for comments. For example, I’m not going to remember what x stands for 40 lines later, but minLength does the job. Variables should be nouns. Method and function names should have action names. If not, it is easy to expect a method to be some property.

Don’t overload the buffer.

An overloaded buffer slows us down. Like CPUs, humans have limited short term memory. Try breaking your code into smaller units. Limit the amount of things a person has to remember to understand parts of code. Methods should just do one thing. If you have a bunch of conditionals, keep code within the initial if / else if clauses brief, and leave the complex bit inside the final else. This way, the reader has to remember less.

Write to be tested.

Keeping methods short and focused also serves another purpose – unit testing. Focused methods means easier to write unit tests. The faster I can get through writing unit tests the happier I am.

And finally…

In the end, you are writing code for other people – other developers, your team, your users, and finally your future self. Keep them happy, then you will be happy.

billandted

It doesn’t hurt to have a boy scout mentality, to leave any place you visit cleaner than when you found it. When this habit is ingrained, it becomes effortless to subtly improve code every time.

Save poetic experimentations for personal projects. However, there is always the chance your future self that may look back on it and have no idea what you did.


(A quick recommendation for all you lit lovers out there: If Hemingway Wrote JavaScript. Angus Croll’s book is a fun read and a testament to the expressiveness of JavaScript.)

Advertisements