Self-documenting code

Introduction

Mastering a skill is a process that always consists of a lot of stages you need to go through before you can finally be where you want to be. Programming is not an exception. At first, you learn some basic concepts, then a particular language with its syntax and peculiarities. You write your first code, wrestle with your first bug, etc. After some time you come to a point when it's not enough to just write a code that works as intended. Now you need to learn how to write good code which not only improves the performance of your program but is also clear and easy to read. In this topic, we will focus on that 'clearness' part of this statement and get familiar with the concept of self-documenting code.

What is self-documenting code?

Self-documenting (or self-describing) code speaks for itself: it's clear, self-explanatory, and well-structured. The reasonable question is: why does it even matter if source code is meant for machines? Why should we care about the way it looks if it works just fine?

There are several reasons, actually:

1. If you used your program a while ago, self-documenting code can save you a lot of time. You don't need to reinvent the wheel and figure out how exactly your code works all over again, it should be enough just to look over it.
2. All the code you write is not something you use only once and then forget for good. Some techniques or pieces of code are universal and might as well be useful in other situations. Just imagine how precious self-documenting code is in that way! If you've already gotten through something, why do it again from scratch?
3. Self-documenting code not only helps you better understand what's going on in your source code but also helps others. Imagine you're doing some project for yourself and decide to make it open. Someone might get interested in it too. If your code speaks for itself, people understand your work better, dive faster into it, use it themselves and, if you have some trouble finding a bug, help you with it.
4. Self-documenting code is a good practice in general for the future. The more you code, the better it gets, right?

Of course, it might be frustrating, pretty time-consuming at first, and not really possible sometimes. However, utilizing such tools as documentation and self-documenting code is considered a good manner in programming and shows your proficiency. So, don't worry, you'll get there!

Now that we've learned why self-documenting code might be useful, let's look at particular ways of making your code self-explanatory.

Ways of writing self-describing code

Self-documenting code uses all possible ways of making itself self-explanatory, clear, easy to read and to understand. What are those ways? Let's name a few:

• choosing names for variables, functions, classes that speak for themselves (e.g. phone_number, book_on_the_shelf, to_upper_case(word));
• splitting large or repetitive pieces of code into functions/methods;
• structuring and ordering your code in a logical way;
• shortening code when possible but not at the expense of its readability.

Summary

In this topic, we've learned what self-documenting code is, how to write it, and why it might be important to regularly practice it. With practice, you'll have a better understanding of what works for you and others, so your way of documenting will get better and less time-consuming as well.