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

New programmers often spend excessive time learning language syntax, tools, and technologies, believing mastery makes them excellent developers, but real programming requires solving domain‑specific problems and collaborating effectively, which means expressing ideas clearly through code.

Robert C. Martin states that comments compensate for insufficient code expression; if code needs comments, it is not good enough. Excellent code should be understandable without comments, with all necessary information embedded in the code itself.

Self‑describing source code improves readability, especially in environments with loose naming rules, facilitating maintenance and extension.

Use Intent‑Revealing Names

Bad examples like

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

obscure meaning, requiring comments. Clear alternatives such as

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

convey intent directly.

Avoid Misleading Names

Names like

Customer[] customerList;
Table theTable;

misrepresent data structures. Better names like

Customer[] customers;
Table customers;

are accurate and unambiguous.

Choose Appropriate Length

While long names are allowed, they can cause clutter. Bad examples such as

var theCustomersListWithAllCustomersIncludedWithoutFiler;
var list;

are overly verbose. Concise yet descriptive names like

var allCustomers;
var customersInOrder;

strike a balance.

Follow Coding Conventions

Adhering to language‑specific style (PascalCase, camelCase, etc.) aids quick understanding. For instance, replace

const int maxcount = 1;
bool change = true;

with

const int MAXCOUNT = 1;
bool isChanged = true;

, and use proper naming for interfaces, classes, and methods.

Use One Term per Concept

Consistently use a single word for a concept. In the bad code

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

, multiple verbs describe the same action. Clear code unifies terminology:

void GetSingleData();
void GetDataFiltered();
void GetAllData();

.

Use Domain‑Relevant Names

Names should reflect the problem domain. Instead of a generic

public class EntitiesRelation { Entity o1; Entity o2; }

, a domain‑specific name like

public class ProductWithCategory { Entity product; Entity category; }

improves comprehension.

Leverage Contextual Naming

Names should fit their context. Redundant prefixes like

string addressCity;
string addressHomeNumber;
string addressPostCode;

are unnecessary; a dedicated

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

provides clear context.

Summary

Effective naming in code means using meaningful, appropriately sized names that follow conventions, avoid multiple terms for the same concept, and reflect domain and context, thereby making code self‑describing and easier for others to understand.