Readable Code

Code is text, technical text, and you or someone else will need to maintain it.

Readable code goes beyond coding standards and visuals, readable means that a human can easily understand it.

An IDE or text editor will make a good job with visuals like fonts and colors, and a good code standard will align how code is written in a given language, and yet it is not enough to make your code readable.

Readability becomes critical when working on a team where every developer has different preferences and backgrounds.

If you have not read my introduction to good code: "What is good code?", please do it. It will take you just a couple of minutes and will give you the context to follow this post.

---

Legibility vs Readability (In the context of writing code):

Legibility:

Composed by two factors: "Visuals" and "Code Standards".
Visuals refer to the job of the computer and the editor in regards to fonts, screen resolution and the overall presentation of the code in the screen.
Code standards refer to spacing, brackets, tabs, case, new lines, etc.

Readability:

Is the human aspect of writing code. Refers to good practices on how to name methods, classes, folders and other elements supported by code standards.

---

Code Readability

You want code that looks almost like pseudo code.

Regardless of the programming language,  you have control of how you name files, folders, variables, methods, classes, procedures, etc. Use these elements as labels to produce readable and "self documenting code".

There should be one single common spoken language.

People all over the world may read your code. There is a high chance that the persons writing and reading a piece of code don't speak the same language.It makes sense to write code in English, even if it is not your first language (my first language is Spanish). It makes since because the most common programming languages use English words as part of its core components anyway. If your organization uses a language other then English use that one instead (you will have to adapt my tips to your language)

Unlike novels, code seeks beauty in consistency and simplicity.

How to write readable code?

Lets focus on five basic ideas:

• Verbs mean actions or questions, used them for methods
• Nouns represent items or things in general, use them for class names (in singular) or collections (in plural)
• Adjectives and characteristics are variables or properties
• States represent current boolean conditions. For instance an engine that is started, has a variable named "started" and a method called "IsStarted"
• Capabilities are usually boolean conditions. For instance an engine that "can start", has a method called "CanStart"

Naming your classes:

Classes are a noun or a noun phrase, use singular. For instance: Car, BookPage
Avoid generic words like Manager, Processor, Data, or Info
Use the prefix “I” for interfaces.

Naming your methods:

Methods represent actions or questions.
Names should indicate what action is been performed or the question been asked.

Basic indicators of bad code naming:

You need to explain what it does by saying: "what I meant was", "it should have been named", "ooh this thing does…"

Rename it as what you meant, what it should have been named, what it does, etc…

You can't decide the name because the method does more than one thing

Simplify. Split it in several smaller classes or methods.

You can't decide the name folder because it contains files of different types

Simplify. Group files on separates folders, so there is one folder per file type

What vs How:

When writing or reviewing a method name, asking the following questions is very helpful.

"What does it do?"

• The name of the method should answer this question.
• There should be no need to read the internals of the method.
• Should contain only one verb.

"How does it do it?":

• The internals of the method should answer, not the name.
• Should be a series of other readable elements.

The "Then" test:

This is a simple, consistent and powerful tool to validate that you have readable code.

They key is to read your code aloud as if it was prose.

Your code should be structured into several simple, consistent and readable methods.

Methods are composed of two kinds of elements:

• Defined by the programmer. Read this ones as prose
• Defined by the language (try, if, for, etc). Read the elements defined by the language in a functional way, for instance
  If: If MethodCall is true then

Test Steps

1. Ask "What does it do"?
2. Read the name of the method aloud. It should give you a clean answer.
3. Ask "How does it do it"?
4. Read the internals of the method one by one, saying "Then" between each one
5. Repeat from 1 for every method

If you can read you code without much pause and it is understandable,then you have achieved your goal.

Final notes:

Readable code is much more than syntactic sugar, is not about colors and fonts.

It's about been able to express with clarity the purpose of your code.

Whether C#, Java,  ColdFusion,  Erlang, Javascript or any other language, your code has to be able to be readable, this principle can be applied to to every single language I've worked with, regardless of the patterns that you use, the version that you are running or the OS of your choice.

Readable code takes time and practice but is saves time / money in all stages of the life cycle of an application.