How to Write Great Code - (Naming)

While coding, how much time have you spent thinking "What name should I give to this variable?" I have had my share of such moments.

What I wish to explore today is what programmers, designers, readers of code and the general developer community should do to improve how we write code.

Today the code you write will probably power many services, it might end up on a billion devices, how would you like to communicate with fellow programmers?

Applying consistent naming convention in code.

A naming convention is a set of instructions and rules of code structure and style on the consistent naming of classes, functions, variables and other entities in code.

class ThePascalCase
function camelCase
let snake_case
const UPPERCASE

Identify conventions and pick one for a programming language.

Code for humans, not the compiler.

Often we fixate on ensuring that code works. In the process, we write code for browser engines, compilers and interpreters.

We communicate with machines through code and the thing about machines is that they already know what to accept and what to do with it.

Consider a high-level language like Python; once the Python interpreter comes across the print statement it understands that it needs to compute the statement and then output the result.

Avoid code like this.

function fp(data)
    return data

var = ...
fp(var);

Instead, write like this.

function filter_post(post_data)
    return post_data

article = ...
filter_post(article)

Code with intention in mind.

The code should communicate your intention as a programmer to fellow programmers.

Chloe has been tasked with adding a feature to an appointment scheduling application.

The code to create functionality for the new feature requires her to calculate the difference between two dates and then assign that to a variable.

Easy right? Let us look at the function.

function dateDifference(date) {
 //Calculate the difference
}

Let's assume that technically the function has no errors.

Even so, the brewing problem is that by just reading the code we can hardly tell the programmer's intention.

• Are we returning a result?

• Are we getting the timestamp or difference in days?

• What is the context of the date argument?

Sometimes we might think of putting it off with some seemingly valid excuses like it is just a hobby project or it is a one-and-done thing.

Well, believe me, you are not the same programmer you were last week.

That hobby project's code is what you paste into your next project or better yet, for all the bad reasons that hobby project becomes your next viral product.

Remember, to write for humans, not the compiler.

The revised code leaves little room for assumptions; the code intent is explicit.

• We are returning the value in days.

• We are passing the appointment date as our argument.

function getDaysTillAppointment(appointmentDate) { 

}

This even makes running tests easier.

When we write generic and vague code we leave the mind to assumptions, which then lead to conclusions that give birth to bugs, then we debug, precious time that would have been spent building a product.

There are few places where you would be justified to use generic code like when you will be reusing the code again.

But even then we can write a function like this, and then use it in appropriate contexts.

function calculateDaysDifference()

Avoid one-letter variable names.

I am guilty of this one.

By explicitly naming variables, you train yourself to articulate the intent of code.

Suppose the common and 'justifiable' one-letter counter variables

let i; 
for (i=0; i<=23; i++) {
    ...
}

Again, we should ask ourselves the intent of this particular code.

If there is no intention to code then I believe, that code should not exist.

For the above code snippet, the question is, what state is the single-letter variable tracking?

Avoid the use of established names.

Names that infer an already established language construct should be avoided.

Refrain from using data type names as variable names, for it is usually a confusion catalyst.

Some programmers code in different languages using statically typed often verbose programming languages. (Yes… talking about you Java).

Using variable names like vector, bool, int, float, number, any data type or a name that is specific to a programming language will confuse.

str
bool
int
double
foat
const
var

Flow of Code.

You reference a method on line 25 defined on line 236.

Beginner programmers unaware of utilising an IDE and Code editors to locate method definitions end up making scroll trips or (CTRL + F) presses.

That is hectic and time-wasting as it will surely interrupt the flow of code searching for definitions way down the reference.

This breaks the reading flow and makes the experience of reading code a chore.

How about the pure methods at the top and composite ones follow?

I am not advocating for a top-to-bottom readable code (if possible go for it) but at least make the flow of code predictable and easy to follow.

Code written and named with intent strengthens code flow, as it is self-descriptive.

The human brain has evolved to associate, simplify and find shortcuts we programmers should use that to our advantage.

How can we then always produce well-written code?

But I will write comments for the code...

When you change the function will you update the comment?

I prefer writing descriptive code then writing the comments later.

Because I know that should I change the functionality of the code I will be forced to update the naming to reflect my intention.

Follow a Coding Style and Standards guide.

Always aspire to ensure that your classes, methods and properties follow a specific style like sort of your code signature.

Failure to adhere to a set of standards will slow down a collaborative project.

Developers working on a project have differing styles and standards the solution to this is following a style guide when writing code.

If you are opinionated, embrace collaboration and try finding ways to make it work by utilising an IDE or rewriting the code.

The style guide decides whether it is Tabs or Spaces, camelCase PascalCase, return 0 or false, Indentation among other aspects.

Well-written code is harder to write but easier to maintain.

Hope you have learned something and will apply it in code.