# 5 Tips for better code readability

David Lambauer — Sun, 11 Aug 2019 10:44:13 +0000

Recently, I was hired to refactor a huge codebase that was messed up for years. The project was a Magento 2 project with more than 30 custom modules. The modules basically did everything you shouldn't do in Magento. I didn't find any tests or documentation. No static code analysis, nothing. The fact, that there aren't any tests is the reason for the messed up code base.

While I was studying the code, I stumbled over the same ugly patterns over and over. This article is a small summary of the 5 worst patterns.

#1 - Chained Function Calls

Chaining... Look at the following:

Chained function call are hard to debug, harder to read and difficult to understand. While debugging, you have to evaluate each of the function calls or step into them instead of just jumping over them...

A better approach would be:

#2 - Yoda Style

It might be a preference of some, but for me yoda style is one of the most unreadable style ever. Maybe my brain is not fast enough to evaluate the condition, maybe yoda style is the pure evil.

Here's why:

Do me a favor and stop doing it <3.

This feels so much more natural:

#3 - Missing early exits

Fail fast, fail loud. That's a common statement when writing public functions. I often see functions doing a lot of stuff before they fail because a given parameter has a value that was not expected. Fail fast, fail loud. Validate incoming params first, fail if they're not matching the requirements of the functions, otherwise continue;

Invert the conditions and add early exits.

#4 - Unnecessary else statements

When an if block is guaranteed to exit control flow when entered, it is unnecessary to add an else statement. Exits can be returns, throws, continues, breaks.

I would say, that else-statements aren't necessary in most cases. Isn't the following code much better to read?

#5 - Naming...

Old but gold. People still give a sh*t about how they name things. Naming is hard, I know. Nevertheless, here are some rules of thumb for many use cases:

Suffix Class Names with their purpose.
- CreateCustomerAccountService
- ImportProductManager
- ProductToArrayMapper
- ProtectHttpConnectionsGuard
- DateTimeHelper
Try to find meaningful variable names and add the following names to your variable-name blacklist:
- $data --> $productData
- $params --> $requestParams
- $model --> $product
- $message -> $userFlashMessage
- $id --> $cartId
- $item --> $cartItem
- $connection --> $redisConnection
Explicit function names. We all know, that our functions shall only do one thing. This in mind, there can be functions similar to each other but having different interfaces. Let's imagine a CustomerMapper Class, mapping customer data. Methods can be named like:
mapToArray(Customer $customer)
mapToJson(Customer $customer)
mapToArrayById(int $customerId)
mapToJsonByEmail(string $email)
For sure, we all work with return types nowadays but it's still a good idea to declare function names that return a boolean like so (Thank for the hint Pujan Srivastava)
- hasStock() : bool
- isGuest() : bool
- canBeAddedToCart() : bool

Disclaimer: Snippets are meaningless examples.

Have an additional tip? Looking forward to hear it

Architectural Decision Records in a Nutshell

David Lambauer — Mon, 29 Apr 2019 05:39:36 +0000

Developers know that software architecture is important stuff.

For novice developers, though, there may be a bit of confusion on how much control one may have in the architecture of a piece of software. This is where Architectural Decision Records come in.

But just what are ADRs, and why are they so important for developers to learn about? Let’s dive into everything you need to know about ADRs.

What are Architectural Decision Records?

Architectural Decision Records (ADRs) are documents that capture a vital architectural decision made, plus its context and consequences. ADRs are common practice in software development and software architecture. ADRs are typically used in addition to common documentation but provide a sort of history.

An Architectural Decision (AD) itself is a software design choice, one that addresses an important requirement in the system. Architectural Decision Logs (ADL) are collections of all ADRs that have been created and maintained for a certain project or organization. An Architecturally Significant Requirement (ASR) is a specific requirement that has a quantifiable effect on the architecture of a software system. All of these titles are used within the topic of architecture knowledge management (AKM).

How and Where to Use ADRs?

There are various areas one can use ADRs in a project and a number of steps one can take to implement them:

Decision enforcement and enactment

ADs are used primarily in software design, so they have to be communicated to and accepted by the people that fund, develop, and operate the system. This often includes sponsors, stakeholders, and producers but also the developer team itself.

Architecturally apparent coding styles and code reviews will need to be implemented. They should focus on architectural concerns and decisions. ADs also have to be considered when modernizing a software system in software evolution and implementing new elements.

Decision-sharing

Using ADRs for decision-sharing is definitely optional, but many ADs reoccur across projects. Because of this, experiences with past decisions in the project can be valuable assets when employing a new and outward knowledge management strategy. Keep in mind that group decision making is often an active research topic.

Decision documentation

Many templates and tools for decision capturing exist. Look into agile communities, such as M. Nygard's ADRs. You can also look into traditional software engineering and architecture design processes, such as table layouts suggested by IBM.

Decision guidance

Quite a few decision-making techniques exist. These include general techniques and software architecture-specific ones, such as dialogue mapping.

Identifying decisions

Ask yourself (or your team): Just how urgent and how important is the architectural design for this project? Does it have to be figured out now, or can it wait until we can figure more stuff out?

This is where having a good team in. Having a mix of personal and collective experience, in addition to recognized design methods and practices, can help substantially with decision identification.

Ideally, you should create and maintain a decision backlog that works with the product backlog.

Architectural Decision Record Example

To give you a brief example of how am ADR might look like, I've added an example:

# 1. Use Typescript for all JS related tasks

## Status

Accepted

## Context

The Frontend Team encountered that the Frontend Code Base is growing too fast. Due to that, the code quality suffers. 

## Decision

Introducing a static-typed language as a superset of Javascript shall help to deal with this situation. All JS related tasks will now be written in TypeScript.


## Consequences

All components of the Frontend Workflow have to be refactored to the new built. In addition, all old plain js files should be rewritten in TypeScript.

DEV Community: David Lambauer