The Art of Readable Code: Takeaways
Tags: csharp, beginners, books, review
Published: 2022-01-11 15:06:53

_I originally posted an extended version of this post [on my blog](https://canro91.github.io/2021/12/20/TheArtOfReadableCodeReview) a couple of weeks ago._

The Art of Readable Code is the perfect companion for the [Clean Code](https://canro91.github.io/2020/01/06/CleanCodeReview). It contains simple and practical tips to improve your code at the function level. It isn't as dogmatic and strict as Clean Code. But, it still deserves to be read.

These are some of my notes from the chapter "Surface-level improvements."

## 1. Package info into names

### If it something is critical to understand, put it in a name

**Choose specific words for your method names**. For example, does **def GetPage(url)** get the page from the network, a cache or a database? Use **FetchPage(url)** or **DownloadPage(url)** instead.

**Avoid empty names like retval, tmp, foo**. Instead, use a variable name that describes the value. In the next code sample, use **sum_squares** instead of **retval**.
	
```javascript
function norm(v) {
	var retval = 0;
	for (var i = 0; i < v.length; i++) {
		retval += v[i] *v [i]; // Prefer, sum_squares = v[i] * v[i];
	}
	return retval;
}
```
	
**Variables i, j, k don't always work for loop indices**. Prefer more concrete names. Indices could be misused or interchanged.

**Use concrete over abstract names**. Instead of **--run-locally**, use **--extra-logging** or **--use-local-database**.

**Attach extra information to your names**. For example, encode units. Prefer **delay_secs** over **delay**. Also, encode extra information. Prefer **plaintext_password** over **password**.

**Do not include needless words in your names**. Instead of **ConvertToString**, use **ToString**.

## 2. Write Names that can't be misconstructed

### Make your names resistant to misinterpretation

Does a method on arrays named **filter()** pick or get rid of elements? If it picks elements, use **select()**. And, if it gets rid of elements, use **exclude()**.

```javascript
// Does results have elements that satisfy the condition?
// Or elements that don't?
results = Database.all_objects.filter("year <= 2011")
```

**Use Min and Max for inclusive limits**. Put "min" or "max" in front of the thing being limited. For example,
	
```python
if shopping_cart.num_items() > MAX_ITEMS_IN_CART:
	Error()
```

**Use First and Last for inclusive limits**. What's the result of **print integer_range(start=2, stop=4)**? Is it [2,3] or [2,3,4]? Prefer, **print integer_range(first=2, last=4)** to mean [2,3,4].

**For booleans variables, make clear what true or false means**. Use is, has, can, should, need as prefixes. For example, **SpaceLeft()** or **HasSpaceLeft()**.

**Avoid negated booleans**. For example, instead of **disable_ssl = false**, use **use_ssl = true**.

**Don't create false expectation**. With these two names **GetSize()** and **ComputeSize()**, we expect **GetSize()** to be a lightweight operation.

<figure>
<img src="https://source.unsplash.com/cHX_Eih2hkY/600x400" alt=""Your Name Here" Sign on the Side of a Building" />

<figcaption>What name would you put in that sign? Photo by <a href="https://unsplash.com/@austinkirk?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Austin Kirk</a> on <a href="https://unsplash.com/s/photos/name?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></figcaption>
</figure>

## 3. Aesthetics

**Similar code should look similar**. Pick a meaningful order and maintain it. If the code mentions A, B, and C, don't say B, C, and A in other places.

For example, don't do,

```python
details = request.POST.get('details')
location = request.POST.get('location')
phone = request.POST.get('phone')

if phone: rec.phone = phone
if location: rec.location = location
if details: rec.details = details
```

## 4. Know what to comment

### Good Code > Bad Code + Comments

**Don't comment what can be derived from code**.

Comment the why's behind a decision. Anticipate likely questions and comment the big picture. Comment why you choose a particular value or what it's a valid range. For example,

```csharp
public const int MAX_THREADS = 8; // Up to 2*num of procs
```

## 5. Make comments precise and compact

Use comments to show examples of input and output values.
	
```java
// Strip("ab", "a") == "b"
String Strip(String str, String chars)
```
	
```c
// CategoryType -> (score, weight)
typdef hash_map<int, pair<float, float>>
```

**Use named parameters or use comments to make the same effect**. Prefer **connect(timeout: 10, use_ssl: false)** over **connect(10, false)**.

In languages without named parameters, use comments to emulate named parameters. Like this,

```csharp
connect(/*timeout_ms=*/10, /*use_ssl=*/false)
```

Voilà! Writing compact and descriptive names is a recurring tip when writing clean/readable code. The Art of Readable Code is a good starting point to introduce the concept of readability and clean code to your team. Give it a try! I found it easier to read than the Clean Code. Both of them are complimentary reads.

***

_Hey, there! I'm Cesar, a software engineer and lifelong learner. Visit my [Gumroad page](https://imcsarag.gumroad.com) to download my ebooks and check my courses._

_Happy reading!_