Writing Great Code

Build a Twitter Analytics App

1 Introduction: Start Here

2 The First Step: Design Your Solution

3 In Which I Rant a Little

4  Design Solution

5 Writing Great Code

6 Writing the Backend Twitter Server

Writing the Code in Small Parts: Part 1, The Basic App

Part 2: Adding a Counter to Exit

Part 3: Adding Language and Retweet Count

Part 4: Organising Our Code

7 Adding the Data to a Database

8 Testing: What and How to Test

8.1 Testing Our Frontend

8.2 Testing Our Backend

9 Displaying our Data using the Flask Webserver

9.1 Introduction to Flask

9.2 Adding templates to our Flask app

9.3 Displaying our Tweets in the Flask Web Server

10 Future Work and Improvements

Writing code is an art as much as a science. And that’s why you have so many debates and arguments about what the best way to write code is. Most of these arguments boil down to My Way is the Right Way (TM).

I’ve had these arguments too, and am not on speaking terms with many people now. I live in the UK, where guns are rare. If I had been in the USA, I’m sure someone would have been shot.

That said, there are a few principles that will help you write great code:

1. Code is read a million times, written once

If you forget everything else, remember this: That hacky, crappy piece of throwaway code you write today might be the running the most critical system in five years. Which is why I say, change your job often, so you can’t get blamed when it all fails.

Code is read more often than it is written. Remember that. So try to write clean code. Clean code is self documenting.

So no:

The code above has a lot of comments, yet is hard to read. The comments have a WTF quality.

Here’s the same code written without a single comment:

No comments, but it’s clear what I am doing. Everyone knows what an average is, you don’t have to tell them you are adding two numbers and dividing by 2.

So when should you use comments? When it’s not clear from the code, or when the reader may be confused. Remember, there is always someone reading the code. Here is a useful comment:

This comment is useful because 6 months from now, you’ll forget why you wrote this code.

Another example:

Here, even though you can see what is going on, you may not know why. This is another reason to write comments. In this case, we are telling the reader why we are doing it this way, and linking to the spec document, so they can check for themselves.

2. Follow a coding standard

It doesn’t matter what the standard is, follow one.

This makes it easy for people who come into the project later to write code exactly the same way as you wrote it. It also makes code easier to read, as the variable/function names  are consistent, as is the formatting / layout of code.

Python has pep8, but don’t become fanatic about it.

3. Your code should be modular / independent

What I mean is: Each part of the code should do one & one thing only. This means: No global variables, no code spread all over the place. Use classes / functions as appropriate.

Modular code is easy to test, easy to debug, easy to extend. That’s because if a part of the code goes out of date, you can update that, without worrying about breaking a million other things.

4. Easily testable

Related to above. If your code is independent, you can test each part by itself. We will cover testing in more detail later on.

5. Follow KISS, or Keep It Simple, Stupid

One of the problem I have with most tutorials is that they overcomplicate everything. To do the simplest thing, like print hello world on the screen, they’ll have a dozen classes calling each other. It seems many Python bloggers come from Java!

In Python, using classes for no reason is considered an anti-pattern.

Later on, we’ll see when to use classes. Always start the code simple– just procedural code. Later on, use functions for repeated code. If you have a fair number of functions, put them in a class. But don’t start with a class; start simple, and add complexity later on. Don’t worry, this will become clear when we look at examples.

6. Code should be resilient

You will have bugs; there is no avoiding that.

What you want to avoid is when a bug in the code that displays LolCat images on your screen destroys your database.

Errors should be handled as early as possible. Errors in one part of the code should not corrupt other parts. This is hard in practice, and requires some critical thinking and code reviews to get right.

7. Manage version  hell / system dependencies

Version hell happens when code works on one machine, but not another. I have written a whole blog on this topic, so I won’t repeat that.

Next: Let’s start coding!

Leave a Reply

Your email address will not be published. Required fields are marked *