Code style matters

Have you ever wondered how your code looks? Exactly - no what it does or even how it is organized, but actually how it looks. One may think here “oh screw it”, but I want to present that it can matter and show you my various thoughts about that topic.

Recently Andrzej Krzywda raised a sensitive issue about code refactoring in Rails Refactoring Book. It provides a brief understanding about existing pains, possible solutions and gives us an opportunity to discuss it more detailed here. This article is intended to be a supplement for that book to show that not only architecture is important.

Why does it matter?

In the beginning I’ll start with some examples in Ruby, that may lead to inconsistency in one project. That’s not a comprehensive example but an overview to introduce this problem.

:key => 'value' vs. key: 'value'

If you decide to use new ruby (>= 1.9), use also a new hash syntax, or if you are so used to the old one, keep it everywhere in your project, independent of your current mood.

'some string' vs. "some string"

Why to use double quotes when not interpolating anything?

result = nil
if some_condition
    result = something
else
    result = something_else
end

vs.

result = if some_condition then something else something_else end

vs.

result = some_condition ? something : something_else

Here ternary operator is less verbose than if, then, else, end, which are used rather in complex (multiline) cases.

or, and vs. &&, ||

They can be really tricky so it is not recommended.

['a', 'b', 'c'] and [:a, :b, :c]

vs.

%w(a b c) and %i(a b c)

Much nicer and no ' everywhere.

I chose these, because I see them the most often. I hope they show that problem exists.

Why I’m pointing on that? Because I’m working in many projects with many devs at one time. I’m using up to 6 different languages every day so sometimes it’s kinda overwhelming. To easily dive into one project from another, switch contexts, jump between environments and work with other people, some guidelines must be respected.

Moreover I’m developing in JetBrains tools (RubyMine, IntelliJ, AppCode, AndroidStudio), which have really nice syntax check inspired by official guidelines like e.g. “Ruby Style Guide” and they help me to keep my code clean and coherent across files.

What is important?

In my opinion, the most important thing about our code is readability. Why? Because we don’t usually have time to read and parse others code. We need to use it. If we are using the same style, we can just take a look and understand everything.

It’s much tougher to understand

unless condition
    something
else
    something_else
end

rather than

if condition
    something
else
    something_else
end

Isn’t it? So the in the first example something will be executed if condition is not true so if it false, yep? Even if parsing takes only a couple milliseconds, when we have a lot of places like that, it may cause wasting more time to refactor code inside our minds.

The other important thing is communication between developers which is done mostly through our code. When we don’t understand what they did and have to reinterpret their code, it means that communication fails. When everyone writes code that have the same look, it’s super-easy to make our work faster. How may times did you have to rewrite a part of code that someone wrote and now you have to implement a new feature? How many times did you complain on others work, because you would do it better?

Where’s the problem?

The main problem is that the taste is sooo subjective. There may be pedants, some that like “artistic mess” or people that don’t care at all. It might be hard to have each of them in one project working on the same code.

Tastes differ. That’s why some writes key: value and some key : value. Some leaves empty lines (one or more) between methods, some don’t do that at all. Some take care of architecture and code separation, but don’t take care of their syntax. Small things, but can be annoying for those that pay attention to such issues.

Of course there are developers which deal with legacy code very well. They easily understand the most tenebrous code, they have huge experience and great skills to interpret any part of existing software. If you are one of them, you may see this blogpost useless, but beware — not everyone is like you. Some learn slower and bad code may discouraged them permanently from the very beginning.

How to solve it?

We cannot have a silver bullet here. Unfortunately code style is really personal and usually hard to change. It’s like old behavior or routine repeated all the time so do not expect immediate switch just like that. So where to begin? A very good start can be guidelines or best practices defined by community or language authors. That may be easy to begin with, learn and improve your code style. There are tons of them for nearly every language. Sometimes even companies define their own guidelines to make it easier and keep concise code across many projects.

How to use them? It might be hard just to remember and use this new code style or guidelines so let’s configure your favorite IDE, find suitable package for Sublime, bundle for TextMate or plugin for VIM that will let you auto-reformat your code. They are usually called YOUR_LANGUAGE-[prettifier | beautifier | formatter] and are available for probably every tool you use to write the code.

Some examples of these guidelines:

Summary

If you think that it’s important topic in your daily work and you are willing to improve your code style I’d recommend you to start from some useful resources guiding you by small steps that will make your code better. Start with small steps, not with everything together. Make a little changes continuously introducing more and more new elements. You’re probably using a few languages at one time so pick one you want to improve and focus on it to avoid too much changes together and decrease new things to remember. Finally, if you want to know our opinion, take the most from Rails Refactoring book.

More useful books that will help you keep your code clean: