Zen and the Art of Coding – Simone Tellini

Writing software is an art: some say it’s a black art (usually right after Word decided to crash taking their last two hours of work to hell ;-)). Someone even considers it a magic art, which reminds of an Arthur Clark quote: “Any sufficiently advanced technology is indistinguishable from magic”.

Like other arts, it has its canons: rules, principles that define how a piece of software should be written. In this post, I’m talking about the style, not the language. Every software developer seems to have his own set of rules: I usually end up arguing with everyone about them 🙂

I’ve decided to write this post, and hopefully other ones, to explain my coding style and the rationale behind it, especially in the vain effort to get my colleagues to agree with me 😉 or at least, to comment with their point of view.

Let’s start from the dogma:

Code should be easy to read

I do mean “read”, not necessarily “understand”: it’s hard to understand something if you find it difficult to read.

You should be able to pick up a piece of code written by someone else and scroll through it grasping its structure at a glance, without having to read every single word or character. You might be looking for a single spot to fix in a huge file and you don’t really want to stay overtime just to find it. 😉

This has always been my #1 rule and it’s usually the first answer I give when someone asks me “why the heck do you write declarations like that, functions this way and expressions that way?” 🙂

Let’s see now how my coding style it’s just an application of the dogma.

Namespaces, classes and methods

I write all these structures using the same style:

the first line declares the block
the opening brace is placed in its own line. The content of the block begins in the following line, without any blank line in between
the closing brace is placed in its own line, without leaving blank lines after the last line of the block

Example:

1
2
3
4
5
6
7
8
9

class Example
{
    public void Method()
    {
        int n;

        // ...
    }
}

I don’t like the Java-style, which is preferred by someone at the office. Why? Because it forces the eye to do more work to recognize the important part of the text: the name of the namespace/class/method.

For instance, look at the following two examples and try to identify the methods as quickly as possible, while scrolling the page up or down:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    public void which() {
        ThisMightBeAnother declaration;
        ThisIsAnother.Kind ofObject;

        // ...
    }

    public void isTheMost() {
        DontGetDistracted lookOnly;
        atTheMethod names!

        // ...
    }

    public void easyToRead() {
        DontGetDistracted lookOnly;
        atTheMethod names!

        // ...
    }

…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    public void between()
    {
        ThisMightBeAnother declaration;
        ThisIsAnother.Kind ofObject;

        // ...
    }

    public void thisAndThe()
    {
        DontGetDistracted lookOnly;
        atTheMethod names!

        // ...
    }

    public void previousExample()
    {
        DontGetDistracted lookOnly;
        atTheMethod names!

        // ...
    }

…to be continued…

Namespaces, classes and methods

Leave a Reply Cancel reply