tldr; This article will discuss important naming conventions used in the software engineering industry to keep code clean.

Some say coding is an art. However, unlike art forms such as painting, beauty is not in the eye of the beholder. We can write code that can be considered “ugly”. The problem is how do we figure out if we’ve just created a Van Gogh, or a first grade hand turkey. That’s the question I’m going to try to answer. I’m going to cover conventions and standards laid out over time by our forefather engineers that have stood the test of time. I know, as always, there might be some disagreement about these practices, but these are generally accepted and in my opinion should be followed.

Background

Personal Experience

tldr; It was at my first internship that I was even introduced to what clean code was

The first encounter I’ve ever had with any form of naming conventions was at a software engineering internship during the summer of my sophomore year at college. I remember going into my first code review naive and starry eyed ready to have my code applauded. However, the first thing I heard was “why are you naming your methods like that, you need to redo them all”. That was my first encounter with the WTF Test !

Clean Code By Robert Martin – WTF Test

tldr; The WTF test comes from the book Clean Code. It’s a way to determine your code quality by having a group of developers review your code, and count how many times they say WTF 😡.

The main source of this article and any following articles about clean code use Clean Code By Robert Cecil Martin as an important source. Robert Martin is one of the best recognized software engineers in history, one of our forefathers 🧙🏻‍♂️. He’s pioneered best practices in clean code, architecture, and agile development. I highly recommend reading his book, and am using it as the basis for my writings.

Now back to the WTF Test. There’s a process coined in the book Clean Code by which we can judge our code quality. The process starts like this. Get a group of developers together in a single room and have them review code together. You’re going to hear a “WTF is does this do” 🤨 in some form from each and every one of them. It’s in the blood of every developer to go “Well actually why didn’t you do it this way” ☝️, mine included. The amount of WTFs you get during a code review is how you judge whether you’ve got clean code on your hands.

Naming Conventions In Our Code

tldr; When naming anything in your code make sure it answers these three questions: Why does this code exist? What does it do? How is it used?

How we name variables, methods, functions, and classes in our code determines how readable, understandable, and clean our code is. The purpose of naming items is to convey meaning to others reading and reviewing our work. When choosing a name make sure that name answers these questions about what it’s representing in the code base:

1. Why does this code exist?
2. What does it do?
3. How is it used?

Formatting Names

tldr; There are 4 formatting cases you can use in your code: camelCase, PascalCase, snake_case, and kebab-case.

When I’m talking about formatting, I’m talking about 4 cases used in naming variables, functions, methods, and classes. These cases are used when separating individual words within our blocks of code. The 4 cases are: camelCase, PascalCase, snake_case, and kebab-case. Each programming language uses at least one of these formatting styles, and we must stick with them regardless! You can have a variation where variables use one style like camelCase while classes use PascalCase, but that means every variable you make must be camelCase and every class must be PascalCase. No if ands or buts 😠. Now let me show you an example of the same variable in each of these styles:

String firstName = "Mikhail";

String FirstName = "Mikhail";

String first_name = "Mikhail";

String first-name = "Mikhail";

Naming Variables

tldr; Variable names should reflect the value the variable is store, so name them using a noun.

Variables are a store of values, and their names must reflect what they’re storing. You can think of them as a box, and our names are supposed to describe what’s in that box. To do that we use nouns in naming them.

For example, let’s say we have a website with users, and we need a variable to store an individual user. This is what our code can look like:

User user = new User();

A simple name like user is perfect for this occasion. Anyone looking at this code will instantly know what's in that variable.

Now let’s take a look at a bad example of the same implementation:

User u = new User();

You might look at that and still think “well that’s not that bad, I can still tell that’s a user”. The only reason that maybe readable is that the Object of our user still follows the clean coding principle. Let’s get rid of that in a language that doesn’t require types like JavaScript:

let u = {name: "Mike"}

Now it’s a lot harder to tell what u stands for. Single letter variable names should be avoided. They’re difficult to understand, difficult to search for, and difficult to reuse. However, there is an exception. Single letter variables are ok when working with loops:

for (int i = 0; i < 100; i++){
	System.out.println(i);
}

Even in these cases do not use the letters l or the letter O, since in some text editors and development environments they may look like the number 1 and the number 0.

for (int i = 0; i < 100; i++){
	System.out.println(i);
}

static int final MAX_CUSTOMERS = 100;

const maxCustomers = 1000;

Naming Methods/Functions

tldr; Functions carry out a task, so their names should be a verb to show an action is being performed

Functions perform an action or carry out a task within our code so we use a verb when naming them. For example let’s say we want to code a method/function to upload a legal document:

public void uploadLegalDocument()

The formatting of methods/functions is language specific, but they also follow one of the 4 mentioned cases in the Formatting Names section.

public Document getDocument();
public void setDocument(Document document);

Naming Classes

tldr; Name as a noun that describes the object

Classes are representations of objects, so we should use nouns when making them that describe the object. For example:

public class Car {}

In Java and many other languages classes follow the PascalCase of formatting.

Clean Code Naming Principles

tldr; The following are coding guidelines that are standard for variables, functions, methods, and classes

The following sections apply to variables, methods, and classes. They are guidelines to follow to make your code readable, query-able, and easily maintainable. Making sure that we pass the WTF Test.

public void updateUser(User user){
  String query = "Insert into user (firstName, lastName) VALUES (?, ?)";
}

Double clickCountDB = 0.0;

Stay Consistent

tldr; When using a certain name to perform an action make sure to use that same name throughout your code

List<String> firstNames = new ArrayList<String>();
List<String> lastNames = new ArrayList<String>();

public void insertFirstName(String name){
  fistNames.add(name);
}

public void addLastName(String name){
  lastNames.add(name);
}

Make Names Searchable

tldr; Use names that are easy to ctrl/cmd + f for and easy to differentiate

String validatedUserNameWithCapital;
String validatedUserFirstNameWithCapital;
String validatedUserLastnameWithCapital;
String validatedUserNameWithoutCapital;

Use Easy To Pronounce Words

tldr; Use names that are easy to pronounce…. kind of self explanatory 😆

String sesquipedalian = tendancy to use long words;

Don’t Add Unnecessary Detail

tldr; Don’t use too much context in your code

int userCountInteger = 0;
User[] userArray;