Clean Code Important Concepts

Which door represents your team? (taken from OSNews)

In my Scrum experience, we have to review our team’s merge requests and give approval before merging them to the main branch. We check for any deficiency in our code and any signs of code smell that might creep our application code. Luckily, the left “good code” door is what mainly represents our team’s code (at least for now).

We, as undergraduate students, have a lot of work to do. We might feel not having time to check others’ code as detail as we desire to. In the face of busyness in the life of stressed-out computer science students, how can we write clean code that is easy to understand at just a glance?

Meaningful Names for Pretty Much Anything

Names are everywhere. We name our variables, our functions, files, directories, whatever. On Github commit activities, renames are the most popular refactorings (77%), followed by move method/class (13%), by extract/inline method (8%), and by extract class/superclass/interface (1%). Because we do so much of it, better do it well then!

Use Intention-Revealing Names

Names should reveal intent. The name should answer all your questions about it. It should tell you why it exists, what it does, and how it is used. Let’s look at an example:

int d; // elapsed time in days

The comment tells us that this variable is about, well, elapsed time in days. If we call the variable elsewhere, will it evoke any sense of ‘elapsed time’? Probably not. A better example would be:

int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

Avoid Disinformation

Avoid leaving false cues that obscure the meaning of code. For example:

• Refer to accountList without it being a list
• The name ajax can mean asynchronous JS, or AJAX Amsterdam
• XYZControllerForEfficientHandlingOfStrings versus XYZControllerForEfficientHandlingOfStrings is very hard to distinguish

Make Meaningful Distinctions

We might code two very similar variables in our first years of programming, like baby and theBaby. Without context, the two are indistinguishable. Usually, we do this because we can’t give two variables the same name — so we add arbitrary changes to satisfy the compiler. A more concrete example is:

getActiveAccount();
getActiveAccounts();
getActiveAccountInfo();

We don’t exactly know the difference between those three just by looking at it. Avoid noise, like a, an, the, or Info or Dataor something else.

Functions

Should Be Small

Lines should not be 150 characters long. Functions should not be 100 lines long. Functions should hardly ever be 20 lines long. Try to make your functions transparent and the intent obvious.

Do One Thing

Functions should do one thing. They should do it well. They should do it only. One way to know a function is not doing “one thing” is if you can extract another function with another responsibility from it.

Have Fewer Arguments

If possible, have zero arguments for a function. If not, you can have one or two arguments. Three arguments should be avoided if possible, and avoid more than three.

Don’t Repeat Yourself (DRY)

Avoid code duplication and structure your functions in a modular way. And if your algorithm needs change, you will not find and replace it from 20+ JavaScript files…

Writing Good Comments

Too many comments indicate a smell of bad code. Rather than using long-winded comments to make up for badly-written code, it is better to clean the code itself. But when is writing a comment necessary?

Informative Comments

// format matched kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile(
“\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*”);

In the example, the comment shows the intended format for time. This helps other developers to understand what time format it takes, rather than figuring out himself from the regular expression.

Explanation of Intent

/* Divide our items among 17 boxes.
* We’ll deal with the leftovers later. */
int items_per_box = floor(items/17);

The code itself is quite clear: items divided by 17. The comment simply tells why the code is here — to divide the items among 17 boxes. Contrast with this:

// Find how many times 17 goes into y, without a remainder.
int items_per_box = floor(items/17);

There is no intent or any indication of usage.

And Many More…

There are still many clean code concepts to learn and practice with that simply can’t be written in here. This article summarizes the Clean Code: A Handbook of Agile Software Craftmanship essential concepts. For more in-depth about clean code, check out the book.

Hope this article helps!