Last Updated: August 26, 2019
· edm00se

Comment Your Code

Incoming rant. Properly translated, this should read as a testimonial to best practices regarding coding, in general. Enjoy it in all its enraged glory.

Comment consistently, comment often. That's it, really. It bugs me that I have to support legacy code that has little to nothing for reference that, God forbid, someone other than the original author might need. I can't even count how many times I've saved my own bacon by describing the major steps to take in my own code; it's that good and takes nearly no time at all. Besides, the old adage of

"if you can't hold your argument up against criticism, then it's not much of an argument"
really applies.

Even if you feel you're too good for commenting it for your own sake, then realize you aren't working in a vacuum; you work for a team. It's either a team you know and shouldn't wish to work against, or it's a team that doesn't exist yet and your crap @$$ code will need supporting after you're long gone.

That's about all I've got. Major landmarks and/or intents for blocks of code. You don't need to hand-hold, but definitely declare what should be happening, maybe why, if you're feeling up to it, and any key ins or outs.

Instead of

"be kind, rewind",

be kind, comment your freaking code!