Write Code You Can Still Read 6 Months Later

#programming #coding #beginners #softwaredevelopment

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

DEV Community