10 Practices For Human-Friendly Code

In programming, it is no news that writing codes is the way to go and it seems like a huge chunk of jargon to a layman. But here’s the point; you are not just writing code for machines to function. You are writing for your future self also. Ever finished a project in a single run without ever needing to look at the code again? I bet your answer is no. When working on an older project, you probably want to spend little to no time figuring out how code works. Readable code is imperative to keep a product maintainable and to keep yourself, and your colleagues or collaborators happy. Code structure and organization helps with readability issues. Group your code to enable easy modification (if you need to scroll up and down multiple times to find your affected section, you need to work on the structure.

Formatting

Of a truth, formatting is not what matters in programming. Adopt a standard format, apply it to the codebase, and automate it. Then you can refocus that energy on actually writing code.

Dead code

Seek and destroy dead code. They effectively say to the reader, “I don’t care about this code”. All those commented blocks, unused variables, and unreachable code are rot.  So a cycle of decay begins. Over time this dead code will kill your codebase. Don’t throw all the code into a single script. While it may seem convenient to have 8000+ lines of code in a single file, debugging is a nightmare when trying to recall method names. Always think about the ease of change.

Nested code

Nearly every code has it’s foundation in logic. Write code to make decisions, iterations, and calculations. This often results in branches or loops which create deeply nested blocks of code. While this may be easy to track for a computer, it can be a lot of mental overhead for a human. As such, the code appears complex and unreadable. Unravel nested code by using guard clauses, early returns, or aspects of functional programming.

Use objects

Despite the current era of Object Oriented Programming, we find this in long parameter lists, data clumps, and custom array/dictionary structures. These can be refactored into objects. Doing so not only formalizes the structure of the data, but provides a home of all that repeat logic which accompanies the primitive data.

Big Blocks

While I don’t adhere to hard numbers, code blocks can reach a critical length. When you determine you have a big block of code, there’s an opportunity to recognize, regroup, and refactor the code. This simple process allows you to determine the context and abstraction level of the code block so you can properly identify the responsibilities and refactor the code into a more readable and less complex block.

Naming

Naming things is hard. But that’s because we make it hard. There’s a little trick that works well with many things in programming, including naming – deferral. Don’t get stuck naming something. Just keep coding. By the time you’re done with the feature or work,  a better name will have presented itself.

Follow Consistent naming conventions. For example, if you name private variables with underscore as the first letter, you should follow through in the rest of your code. If you are working collaboratively, discuss naming conventions before anyone touches the code. Most programming language may now already have their own standard naming conventions either it’s defined by the core language itself or the community (e.g. PHP-FIG). So, most of the time, you don’t have to create your own naming conventions.

You can instead use a so-called linter or code sniffer to help enforcing and fixing your code to conform with these standards. Here is a few of popular linters in some programming languages:

PHP: PHPCS

Ruby: RuboCop

Shell or Bash: ShellCheck

JavaScript: ESLint, and JSHint

Swift: Tailor, and SwiftLint

Descriptive Variable / Method Name

The variable and method name should perfectly describe what that code does. For example uncommon abbreviations like Sort_PT() may be confusing: what does the PT mean? If you can’t answer it on a second check, optimize the name to Sort_PostType() for better comprehension.

There’s an exception though. Most of programmers would already be familiar with the term “ID” for identity so we can always define a variable with the short form, “ID”.

Indentation And Line Breaks

Indentation is magical! With some simple Tab keys, you can reveal the entire code structure and edit the code with a clear understanding of how it will function.

For line breaks, use it when 2 codes on the same line execute different things. For instance, it’s best to not chain CSS properties on a single line — it complicates things.

Symmetry

Symmetry in code is where the same idea is expressed the same way everywhere it appears. Actually, it  is easier said than done. Symmetry embodies the creative side of writing. It’s underlies many of the other practice: naming, structure, objects, patterns. It may vary language to language, codebase to codebase, and team to team. As such, you could spend the term of your natural life pursuing it. Yet, once you start applying symmetry to your code, a purer form appears and the code takes shape quickly.

Leave a Reply