How to Write Self‑Describing Code: Naming Best Practices for Clean Code

Many novice programmers spend most of their time learning language syntax, tools, and technologies, believing that mastering these makes them excellent developers. In reality, programming is about solving domain‑specific problems and collaborating with others, which requires expressing ideas clearly through code.

Robert C. Martin states in *Clean Code* that comments exist to compensate for insufficient code expressiveness; if you need comments, the code is not good enough. Excellent code should be understandable without comments, with all necessary information conveyed directly.

The concept of "self‑describing source code" aims to increase readability, especially in environments with loose naming rules, making maintenance and extension easier.

Show Intent in Naming

Bad naming uses short, ambiguous identifiers that force readers to rely on comments.

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

Clear naming makes intent explicit:

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

Avoid Misleading Names

Misleading identifiers convey incorrect information, which is worse than no information.

Customer[] customerList; // actually a simple array
Table theTable; // unnecessary "the" prefix

Improved versions:

Customer[] customers;
Table customers;

Appropriate Name Length

Modern languages allow very long names, but excessive length creates clutter.

var theCustomersListWithAllCustomersIncludedWithoutFiler;
var list;

Balanced names keep necessary meaning while staying concise:

var allCustomers;
var customersInOrder;

Follow Coding Conventions

Adhering to a language’s naming style (PascalCase, camelCase, etc.) lets readers infer type and purpose at a glance.

const int maxcount = 1; // bad
bool change = true;      // bad

public interface Repository;
private string Name;
public class personaddress;

void getallorders();

Corrected version:

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 a single word for multiple concepts confuses readers.

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

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

Unified terminology improves clarity:

// data retrieval
void GetSingleData();
void GetDataFiltered();
void GetAllData();

// data presentation
void LoadDataToView();
void SetObjectValue(int value);

Use Domain‑Relevant Names

Names should reflect the problem domain so that anyone familiar with the domain can understand the code.

public class EntitiesRelation {
    Entity o1;
    Entity o2;
}

Domain‑aware version:

public class ProductWithCategory {
    Entity product;
    Entity category;
}

Use Context‑Relevant Names

Names should be meaningful within their surrounding context; redundant prefixes can be removed.

string addressCity;
string addressHomeNumber;
string addressPostCode;

Better approach using an Address class:

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

Summary

Choose names that convey a clear concept.

Keep names concise, containing only necessary information.

Follow coding conventions to aid understanding.

Use a single term for each concept.

Prefer names that are meaningful in the domain and context.