How to Write Self‑Descriptive Code: Naming Practices for Clean Code

Why Naming Matters

New programmers often spend most of their time learning syntax, tools, and frameworks, believing that mastering these makes them great developers. In reality, programming is about solving domain‑specific problems and collaborating with others, which requires expressing ideas clearly through code so teammates can understand the intent without excessive comments.

Self‑Descriptive Code

Robert C. Martin states in *Clean Code* that comments compensate for insufficient expressiveness in code. If you need comments to explain what a variable or function does, the code itself is not clear enough. Good code should be understandable without external explanations, and all necessary information should be conveyed by the identifiers themselves.

Bad vs. Clean Naming Examples

Bad naming:

int d; // elapsed time in days
int ds;
int dsm;
int faid;

Here d could mean anything, and faid is easily mistaken for an ID, forcing the reader to rely on comments.

Clean naming:

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

Each identifier clearly conveys its purpose, eliminating the need for comments.

Avoid ambiguous names:

Customer[] customerList;
Table theTable;

customerList

is actually a simple array, not a list, and the prefix the adds unnecessary noise.

Clear version:

Customer[] customers;
Table customers;

Names are concise and accurately describe the data structures.

Appropriate Name Length

Modern languages allow very long identifiers, but overly verbose names create clutter.

Bad examples:

var theCustomersListWithAllCustomersIncludedWithoutFiler;
var list;

Names should contain enough words to express meaning, but any superfluous words make them harder to read. Shorter is better as long as the context supplies the missing information.

Clean examples:

var allCustomers;
var customersInOrder;

Follow Language‑Specific Conventions

Every language has its own style (PascalCase, camelCase, Hungarian notation, etc.). Ignoring these conventions makes code harder to read for other developers.

Bad code:

const int maxcount = 1;
bool change = true;
public interface Repository;
private string Name;
public class personaddress;
void getallorders();

Issues include non‑standard casing, ambiguous boolean naming, and missing context.

Clean code:

const int MAXCOUNT = 1;
bool isChanged = true;
public interface IRepository;
private string _name;
public class PersonAddress;
void GetAllOrders();

One Concept, One Term

Using multiple words for the same concept or one word for multiple concepts confuses readers.

Bad example:

void LoadSingleData();
void FetchDataFiltered();
void GeteAllData();

void SetDataToView();
void SetObjectValue(int value);

The first three methods all aim to “get data” but use three different verbs. The second pair uses set for two unrelated actions.

Clear version:

// 1.
void GetSingleData();
void GetDataFiltered();
void GetAllData();

// 2.
void LoadDataToView();
void SetObjectValue(int value);

Domain‑Relevant Naming

Code should reflect the business domain it serves, making it easier for developers, testers, or other stakeholders to understand.

Bad example:

public class EntitiesRelation {
    Entity o1;
    Entity o2;
}

Names like EntitiesRelation convey little about the actual purpose.

Clear example:

public class ProductWithCategory {
    Entity product;
    Entity category;
}

Context‑Aware Naming

Names should leverage the surrounding context to avoid redundancy.

Bad example:

string addressCity;
string addressHomeNumber;
string addressPostCode;

Since PostCode is inherently part of an address, the address prefix is unnecessary. A dedicated Address class would encapsulate these fields.

Clear version:

class Address {
    string city;
    string homeNumber;
    string postcode;
}

Summary

Effective naming guidelines for programmers:

Names should convey a meaningful concept.

Keep names as short as possible while retaining necessary information.

Follow language‑specific coding conventions to aid readability.

Use a single, consistent term for each concept.

Choose names that are meaningful within the domain and context.