Write Code You Can Still Read 6 Months Later

I'm AlanWu. I'm in junior high. I've written a lot of bad code. Here's what I changed to make it less bad.

1. Name things like a human

// Don't do this

int d;          // days? distance? damage?

int cnt = 0;    // "cnt" — you know, the classic

vector<int> v;  // v of what



// Do this

int daysUntilDeadline;

int errorCount = 0;

vector<int> studentScores;

Full words, no abbreviations. idx instead of i in loops is fine. But sz for size, cnt for count, ptr for pointer — just type the word. You're not being charged by the character.

2. Functions should do one thing

If you need the word "and" to describe a function, split it.

// Bad: does two things, name lies

void loadAndValidateConfig() {

    readFile();

    checkSyntax();

}



// Better

Config loadConfig(string path) {

    return parseConfig(readFile(path));

}



bool validateConfig(const Config& cfg) {

    return cfg.width > 0 && cfg.height > 0;

}

My rule of thumb: if a function is longer than what fits on one screen, break it. If I can't describe what it does in one sentence without "and", break it.

3. Comments explain WHY, not WHAT

// Bad — tells me what the code already says

// Loop through all students

for (auto& s : students) {

    s.score += 5;

}



// Good — tells me WHY, which the code can't

// Extra credit: 5 points for submitting early

for (auto& s : students) {

    s.score += 5;

}

If you're writing a comment that just restates the next line of code, delete it. The only comments worth keeping are the ones that answer "why did I do it this way?"

4. Don't nest too deep

// Bad — 3 levels deep, I've already forgotten what the top level was

for (auto& student : students) {

    if (student.hasSubmitted()) {

        for (auto& answer : student.answers) {

            if (answer.isCorrect()) {

                score++;

            }

        }

    }

}



// Better — flatten with early exits

for (auto& student : students) {

    if (!student.hasSubmitted()) continue;

    for (auto& answer : student.answers) {

        if (!answer.isCorrect()) continue;

        score++;

    }

}

Also: if you have if (a) { if (b) { if (c) { ... } } } with no else, just combine them: if (a && b && c).

5. Split long files

My algorithmCombination project started as one gigantic header. 800 lines. Finding anything was pain.

Now I split by topic:

math_utils.h      // gcd, lcm, fast_pow

string_utils.h    // split, trim, join

data_structures.h // heap, disjoint_set

Each file is under 150 lines. I know exactly where everything lives.

6. The 30-second test

Six months from now, can I look at a random function and understand it in 30 seconds?

If yes: it's good code, even if it's not elegant.

If no: rename things, add one comment, split one function. Repeat until it passes.

I don't write code for the compiler. I write it for the version of me who hasn't slept and needs to fix a bug at midnight.

My GitHub: https://github.com/Cn-Alanwu