3 Essential Tips That Make Your Source Code Shine

With examples in Python and JavaScript

In this article, you will learn about 3 essential tips that will help your source code to rise and shine. See, there are some unwritten laws that every good programmer obeys. Even if you are facing a tight schedule and you try to pump out your code as quickly as possible: You still have to follow these rules.

Even if you are an experienced programmer!

I’m not talking about algorithms, data structures, software architecture and design. I’m talking about something much more fundamental, much more vital: Readability

Source code needs to be carefully crafted. Always. There is no such thing as “quickly hacking around”. If you try to be fast by skipping these basic rules, you always end up being slower in the end.

See, source code is written once, but it is read many times. Optimizing code for readability is therefore paramount. I present to you 3 vital rules you have to follow so that you can produce highly-readable code. Following these rules helps you and everybody else working with your code to maintain, extend and adapt it. Also, readable code is far less error-prone.

The best thing about those 3 rules is: You can implement these rules right away. No training time needed. You will be a better programmer in just minutes!

Let’s start.

Use meaningful variable and function names

A line of code says more than 1000 words. Well, sometimes not. To use self-explanatory variable and function names makes your code so much easier to read, understand, maintain and extend. Here’s an example:

Of course, when writing that piece of code, I knew exactly what kind of formula I was implementing. Do you know as well? Maybe yes, maybe no. I could have added a comment to describe the purpose of that formula, but a much better way is to just use descriptive variable names like this:

Wow, now it’s crystal clear. Just by using descriptive variable names, the reader can immediately learn that this code converts Fahrenheit to Celsius. Now let’s put that code into a function and observe the degree of readability according to function names and parameter names.

Compare the “short” version:

with the more elaborate version:

I know what you are thinking: It takes much longer to write that “long” words instead of just using single letters for variable and function names.

However, let me ask you a question: How much longer does it take to understand a piece of code that is written in either style? Self-explanatory code is not only a big time saver for other people reading your code but even for yourself. How often did you went back to extend or change some code that you wrote 3 months ago? And how often did you think: “Gosh, what the hell did I do here?” Remember:

Code is written once, but it is read many times.

Anything you can do to optimize reading performance is worth the additional writing effort.

Use proper indentation

If you are programming in Python, you can as well skip this tip and thank Guido van Rossum for his decision to make indentation mandatory in “his” programming language.

For most other popular programming languages like C/C++, Java, JavaScript, PHP, C#, PHP, etc. read carefully:

Indent your code hierarchically

I don’t care if you use tabs or spaces. (ok .. I do, but that’s something for another blog post..) I don’t care if you use 3 or 4 spaces. I just want you to understand that indentation is a must in programming. Let’s compare some pieces of JavaScript code. This code:

1. Converts the values from 100 to 110 from Fahrenheit to Celsius

2. Rounds the converted values to 0 places after the comma (making them integers)

3. Outputs to the console all even celsius values (This is done by using the modulus operator “%”, which returns the remainder of an integer division. Thus, 11 % 2 equals 1, and 12 % 2 equals 0)

Compare the non-indented form:

with the indented form:

I also added some blank lines to structurize the code even more. Which of those two code snippets is more readable?

Use Functions (properly)

Create re-usable building blocks by using functions. These also help you to structurize your code and make it more readable and understandable. The most important feature of functions is that they avoid repetitive code. Remember:

Avoid Repetition!

If you see the same lines of text distributed multiple times all over your codebase, you most likely missed to create a function (or a class, or a module, etc… depending on which programming language you use). Let me give you an example:

The above code prints out the 4 values in deg. Fahrenheit and their converted values in deg. Celsius. We can easily see that we are dealing with code duplication here, so let’s get rid of it by creating a function that does the conversion and printing for us:

Much better right? The code looks “clean” and “lean”. Also, it is far more descriptive than the first example. Anyways, we still have that formula residing there in the ConvertAndPrint function. What if we would like to convert Fahrenheit to celsius without printing their values? Let’s extract the formula to its own function:

Et voila! We produced some self-explanatory piece of code that consists of building blocks that we can re-use in many ways in different scripts.

However, we are not done yet.

See, we still have some bit of repetitive code. And our PrintFahrenheitAndCelsius function takes 4 values. But what if you want to print only 3 values. What if you want to print 300? There’s a better way to do this.

Depending on your programming language, there are most likely several options to abstract the number of parameters of a function. What is almost always a valid idea is to use a container (like an Array or a List) instead of multiple variables. See that final example:

This last change made our function far superior:

1. It is shorter and easier to read

2. It is much more generic

Conclusion

Source code is much easier to read (and thus to understand, maintain and extend) if you follow some simple rules / styling guidelines.

Also, we have seen the power of abstraction: Use functions (or whatever means of abstraction the programming language of your choice offers) to create reusable building blocks.

Upgrade your variables and functions by using proper naming so that your source code becomes easy to read. Some people even claim that Source code must read like a story.

Implement these 3 tips, and I promise you, you’ll see amazing results.