Clean Code Basics — Avoid comments and choose better names

5 min readOct 17, 2020

Almost every device contains software. And if the software is developed poorly it ends in a bad customer experience (e.g. no updates will be developed) or even in accidents (if the software doesn’t work properly).

Programming is art and writing good code is difficult. But I want to introduce two aspects of a cleaner code which is super easy to follow: comments and names.

This said, I directly want to introduce two statements:

Comments are evil and should be avoided at any time. Good code doesn’t need comments.
Choosing good names is king. Wisly choosen names makes the code base sustainable.

Let’s look directly into some examples. (Here a summary of cases: camelCase, PascalCase, snake_case, kebab-case)

Case #1 — There is a comment

How many times you have seen something like that.

int $d; // elapsed time in days

If the name of the variable would simply be int $elapsedTimeInDays no comment would be necessary at all, right?

→ Use intention-revealing names!

Did you ever see something like that?

// check if customer is eligible for (senior) benefits
if ($customer->flags && $customer->status === true && $customer->yearOfBirth - date("Y") > 65) {}

How about extract it into a new function.

if ($customer->isEligibleForBenefits()){}

→Use descriptive names!

Case #2 —It can’t be pronounced

Did you ever see variable names like $dircotgs or $modzpsui? If you can’t pronounce the name of a variable, then it should not be used. Instead use better names like $modificationTimestamp and $fileAgeInDays.

→ Use pronounceable names!

Case #3 — It can’t be searched

How about hardcoded values. I remember the HR-Tool of my old company. The reduction of working time caused a giang effort. For example a function calculates the yearly working hours $h = 7 * 5 * (52 — 6). It is almost impossible to find this calculation and it takes more time than necessary to understand what it actually does. (Seven hours per day, five hours a week, 52 weeks a year minus six weeks vacation)

I also want to draw a line here. There are numbers out there we all might know like a year has 52 weeks, a day has 86400 seconds, a year has 365 days. Most programmers will figure that our immediatelly. But for everything else we should pack that in contants or variables (WORKING_HOURS_PER_DAY, WORKING_DAYS_PER_WEEK, WEEKS_OF_VACATION_PER_YEAR). So we receive a much easier to understand version: $h = WORKING_HOURS_PER_DAY * WORKING_DAYS_PER_WEEK * (52 — WEEKS_OF_VACATION_PER_YEAR.

And how about the variable name $h itself. Best practise here is: The length of a name should be correspond to the size of it’s scope. That means within a loop the var i could still be used. But for everything else we should find proper names. In our case $workingHoursPerYear might make sense.

→Replace magic numbers with named constants!

Case #4 — Unnecessary or wrong information

From time to time you will see variable names like $productData, $productInformation, $productList. But honestly, what does data and information even mean? Everything contains data and information, so why write it out? Would you ever write $productNameString instead of $productName? So why adding a data type like list or array to a name? And the worst, $productList could not even be a list.

A better approach would be to save the products in and array or list $products and provide the product as an object $product with attributes like $product->name and $product->price.

→Avoid disinformation and encodings!

Case #5 — Mixing up similar words (Confusion by picking the right method)

Imagine you want to receive product information via an API. There are calls named getProducts() but also fetchImages() and retrievePriceTags() . Isn’t that quite confusing? So just stick to one word per concept. Don’t mix up words like erase, delete, kill, abort, dump and don’t use fancy language like eatMyShorts. Be professional.

→ Pick one word per concept!

Case #6 — Misleading names

Imagine you see the method add(). Does this function perform the addition of numbers or insert a new row to a database? My recommendation is not to pun and to use precise names like insert() or append().

I remember I saw a function called getState($customerId). First I thought it will return something like true or false but in fact it return the state of the country. This is a great example of a misleading method name. Better use a method getCustomer($customerId) which returns the state in the object like $customer->address->state.

→Make meaningful distinctions (Don’t pun)

There are some standards you should follow:

Classes

Use nouns for class names like class Product and class User
Use plural for collection classes like class Countries
Avoid vague prefixes for class names like class MyController
Avoid all capital acronyms like class HTTPAPIPerformer and use PascalCase instead class HttpApiPerformer

Methods / Functions

Use camelCase if applicable
Use present tense verbs for methods like getProducts()
Use prefix gerunds with is or has e.g. isRunning() or hasValidated()
Avoid gerunds (verb + ing) e.g. validating() and past tense e.g. opened()

Variables (and parameter names if applicable)

Use singular nouns for object instances e.g. private $product and plural nouns for arrays and collections e.g. public $countries
Avoid verbs for primitive types e.g. int $create = 3, use nouns instead e.g. int $creationSteps = 3
Avoid single-letter names e.g. string $g
Avoid using the data type as suffix e.g. int $creationStepsInt

“Allowed” exceptions

While you are programming and debugging comments are allowed. We always start to just get things running. Also some comments might be ok at some points (e.g. runtime warnings). While you are programming you also will create new functions. Try to name variables already as good as you can. And the names of functions will become better after refactoring. But before you check in new code in git do your job and make it clean. If you are doing a code review don’t accept bad code as well!

What’s now? Dig deeper!

In this post we did only speak about comments and names. For clean code there are more topics you can dig deeper like function rules and design rules. I recommend watching Uncle Bob on Youtube. It’s entertaining and informative: https://www.youtube.com/watch?v=7EmboKQH8lM. You also should read at least a summary of Clean Code: A Handbook of Agile Software Craftsmanship written by Robert C. Martin.

Sources:

Clean Code Basics — Avoid comments and choose better names

Written by Michael Gerstenberg

No responses yet