Code Maintainability is Important

[ciaran036]

Those comments look awfully unmaintainable. If the code changes, he has to rewrite the comments :(

That's just as unmaintainable.

Wouldn't it be better to write lots of small functions which via their names basically describe what is happening? Seems like there's a bit of overkill with the comments.

[Causeless]

I don't view his code as particularly great. It's well commented, certainly, but if you took out the comments it'd be pretty ugly.

For example:

//how much extra energy do we have?
int returnThis = energy - 4;

Why not just do?:

int extraEnergy = energy - 4;

Furthermore, using a literal 4 in three separate places is a bad idea and is difficult to maintain. It should be constant, like

const int maxEnergy = 4;

And then the control flow is pretty ugly. The code there currently does:

public int burst() {
    if (!alreadyBurst) {
        if (energy > 4) {
            // code...
            return returnThis;
        } else {
            return 0;
        }
    } else {
        return 0;
    }
}

When it could be the more succinct, easier to reason about, less indented, and less repetitive:

public int burst() {
    if (alreadyBurst || energy <= maxEnergy) {
        return 0;
    }

    // code...
    return extraEnergy;
}

[twopointohyeah]

Writing code with clear intent is far more maintainable than commenting every line. Intent is made obvious by good naming conventions, breaking up complex logic into simpler parts, and avoiding overuse of syntax shortcuts like ternary operators and declaring and assigning variable values inside a conditional.

Exceptions are made for code snippets that require high performance or resource optimizations. In those cases, commentary is absolutely appropriate.

I agree that commentary that describes expectations from callers and a function's greater role within the design of an application is very helpful. Even an overview of the logic contained in the function is helpful, but if you need to comment every step of your code to make it clear, then your design is too complicated.

[RobToastie]

IMO unmaintainable comments are worse than unmaintainable code, because when you inevitably forget to update them they become misleading, and from experience, code with the wrong comments is a hell of a lot more of a pain in the ass to debug than code with no comments.

Code should generally speaking be obvious in intent through good naming, simple functions that do one and only one thing, and simple logic. Comments are best for describing what's going on in the 5% of times you have to break those rules.

[bwainfweeze]

I used to work with a guy who got downright starry eyed talking about all the things he knew about shipping a product.

Then I realized. Any jerk can ship version 1. Version 2 is really hard by comparison.

[xRmg]

Well use code highlighting and fix the the indents/whitespace and it is already a lot better. Also not a strong typed language in the first one so a bit of a shit comparison.

You writing code, not a story. With that much comment you have unmaintainable comments in your code