When Are Code Comments Truly Necessary? A Deep Dive into Clean Code Practices

Comments can be useful, but the author argues that clearer, more transparent code often makes them unnecessary.

Four Levels of Code Quality

Level 1 – Worst: Complex, opaque code with no comments.

Level 2 – Better: Complex, opaque code with comments (common in practice).

Level 3 – Good: Simple, transparent code with comments.

Level 4 – Best: Clean, self‑explanatory code that needs no comments.

When to Use Comments

When the code is complex or hard to read.

When the result is not obvious.

When the method’s context is unclear.

When a comment must be as clear and elegant as prose, in any language.

Clean‑Code Practices (Language‑Independent)

Below are refactoring examples that replace poor comments with expressive code.

1. Let Code Speak for Itself

/// <summary>
/// !@#$%^&^&*((
/// </summary>
public decimal GetCash()
{
    //!@#$%^&^&*((
    var a = new List<int>(){2,3,10};
    var b = 2m;
    var c = 0m;
    //!@#$%^&^&*((
    foreach (var p in a)
    {
        c += p * b;
    }
    return c;
}

Refactored:

public decimal CalculateTotalCash()
{
    var itemCounts = new List<int>(){2,3,10};
    var price = 2m;
    return itemCounts.Sum(p => p * price);
}

2. Meaningful Boolean Variables

public bool IsAdult(int age)
{
    bool isAdult;
    if (age > 18)
        isAdult = true;
    else
        isAdult = false;
    return isAdult;
}

Refactored:

public bool IsAdult(int age)
{
    var isAdult = age > 18;
    return isAdult;
}

3. Avoid Double Negatives

if (!isNotRememberMe) { }

Refactored:

if (isRememberMe) { }

4. Eliminate Hard‑Coded Values

if (carName == "Nissan") { }

Refactored:

if (car == Car.Nissan) { }

5. Replace Magic Numbers with Constants

if (age > 18) { }

Refactored:

const int AdultAge = 18;
if (age > AdultAge) { }

6. Reduce Parameter Count

public void RegisterUser(string userName, string password, string email, string phone) { }

Refactored:

public void RegisterUser(User user) { }

7. Remove Boolean Flags from Method Signatures

public void RegisterUser(User user, bool sendEmail) { }

Refactored:

public void RegisterUser(User user) { }
public void SendEmail(User user) { }

8. Write Expressive, Declarative Code

private string CombineTechnicalBookNameOfAuthor(List<Book> books, string author)
{
    var filterBooks = new List<Book>();
    foreach (var book in books)
    {
        if (book.Category == BookCategory.Technical && book.Author == author)
        {
            filterBooks.Add(book);
        }
    }
    var name = "";
    foreach (var book in filterBooks)
    {
        name += book.Name + "|";
    }
    return name;
}

Refactored:

private string CombineTechnicalBookNameOfAuthor(List<Book> books, string author)
{
    var combinedName = books
        .Where(b => b.Category == BookCategory.Technical && b.Author == author)
        .Select(b => b.Name)
        .Aggregate((a, b) => a + "|" + b);
    return combinedName;
}

Additional notes cover DRY violations when merging distinct models, and the use of tools like ReSharper to automatically suggest clean‑code improvements.

Overall, the goal is to adopt a coding style that minimizes reliance on comments by making code self‑explanatory.