Naming Things in Program

#programming #computerscience #cleancode #codequality

There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton

Whether Phil said this quote or not. In my opinion, I totally agree with the naming of things, especially since English ain't my mother language.

Good naming would let your objects proud to ask: "Say my name", and speak loudly like Mr. White in Breaking Bad. So how to name things? There are some concepts that come below.

1. Don't abbreviate names

There is a classic example, you shouldn't name variables with a single letter. That won't tell you anything about the variables, for instance.

❌ int y = 3;
✅ int seconds = 3;

For class or function naming, abbreviating will easily make your team member or other developers who can't realize it at first sight, even yourself(After a few days you are back to check your code). See these instances below.

❌ abbreviate

Public void MoveOnPg()

✅ not abbreviate

Public void MoveOnPage()

2. Don't put types in variable names

Many books before usually recommend putting the type in the prefix of the variable, but now with statically type languages, we don't need to do that.

❌ type variable

bool bIsValid;
int32_t iCount;
uint32_t uNumUsers;

✅ variable

bool IsValid;
int32_t Count;
uint32_t NumUsers;

3. Add units to variables unless the type tells you

The parameters of the function, adding units are clear to whom to use it.

❌ not type variable

void progress(int overdue)

✅ type variable

void progress(int overdueSeconds)

Further, we can add the type instead for this case in C#, and here getting seconds.

void progress(TimeSpan overdue) {
     var seconds = overdue.TotalSeconds;
}

4. Don't put types in your types

There is very common to see people to put types in the types, in particular the pattern in C#, for instance, adding the prefix in interface with "I".

public interface IService
{
    void Configure(IConfiguration configuration);
}

Most of the time people don't care about whether it's an interface, class, or abstract class, they just want to know what they can use, Absolutely, for C# developers it quite makes sense to follow the pattern, since everyone does that, but for other languages, we shall avoid to do it.

Another example is AbstractX, BaseX

class Car: BaseCar
{
    private const double power = 225;
    private const double acceleration= 6.1;

    public Car(): base(power, acceleration)
    {
       ...
    }
}

It's good to rename the "BaseCar" to "Vehicle", and we can also make the child vehicle become a especific vehicle: Sedan.

class Sedan: Vehicle
{
    private const double power = 225;
    private const double acceleration= 6.1;

    public Sedan(): base(power, acceleration) 
    {
       ...
    }
}

5. Refactor if you find yourself naming code "Utils" or "Utilities"

The class "Utils" or "Utilities", isn't a good name to make customers understand what this class can do, until they dig inside, see below.

public class Utils
{
    int number;

    public Utils()
    {
    }

    public int sum(int number1, int number2)
    {
        number = number1 + number2;
    }
    return number;
}

Actually, we don't need this "Utils" class, for the functional we can move this out, and create a sum class instead.

public class Sum
{
    private int result;

    public int Result {
       get {
           return result;
       }
    }

    public Sum(int firstNumber) {
        result = firstNumber;
    }

    public void Add(int number) {
        result += number;
    }
}