DISCLAIMER:
Best practices are fairly POV, and often language specific. However, the author is so full of himself that he's not going to dignify other opinions by writing this from a neutral POV — personal opinions rock, babaaaay!
The founding commandments of maintainability
Thy code shalt not repeat itself!
Pretty self explanatory. Repeated code means more opportunities for mistakes, and desynchronization of blocks of code that needs to be the same. Or worse yet, repeated bugs. It also tends to hide the important code in a mess of repetitive boilerplate. Don't Repeat Yourself (DRY). This includes things like warts which repeat the (supposed) type of a variable fall into this category as well. You already know the type by it's declaration. Describe what the variable represents instead!
Thy code shalt be automatic!
Driving stick may be fun, but manual anything in programming is no fun — it is guaranteed to lead to bugs, and worse yet, often the worst kind of hard to diagnose, find, and treat bugs. Automation is the way to go! Anything you can do to fork more work off onto the computer is a good thing. An exemplementary example of this would be RAII in C++ — without it, you run the risk of leaking resources by forgetting to clean up, which must be done at every possible exit point of a function: returns, thrown exceptions, etc. — and as a result violates DRY. Destructors, on the other hand, being called for all of the above scenarios automatically, are the perfect counter-response.
Thy code shalt be automatically tested!
Automated tests are a wonderful thing, Unit Testing can tell you immediately when you've fucked up, instead of a bug report from some overstressed beta testers (or worse yet, end users) years after the original problem was created, and subsequently forgotten about. Test early, test often, and you'll eliminate bugs quickly and early, as well as avoid mishaps when refactoring accidentally introduces new bugs. Assertions are also wonderful in this regard, basically inlined unit tests for checking preconditions and other contractual programming tools have been correctly abided by.
Thy code shalt be readable!
Code need only be written once, but read many times — for debugging, modification, or just plain understanding what the hell is going on. It follows that readability should trump writeability, then, in the interests of maintainability. A common mistake is to comment anything and everything. This just duplicates information already found in the code — a violation of DRY which only serves to ensure that you will eventually be mislead by a comment that is just downright wrong, without contributing anything of value (new information).
First and foremost, refactor. If something is obtuse, refactor it until the structure makes sense. This involves descriptive names for variables and functions. It theory, it should read as clear as the water of a pure mountain spring without commenting — the code describes itself (otherwise known as "self documenting code"). Takes a bit longer to write, but your future coworkers — or your future self when (not if) you need to revisit your code after having forgotten all about — will thank you.
In practice, some code will be resistant to such descriptive refactoring, due to performance considerations or other concerns. Or maybe you're just using C++. Either way, this is where commenting code starts to come in: you can explain the high level rationale or action of what's being done, leaving the code to explain the seemingly backwards-ass method of getting there. Other uses for comments include TODOs, FIXMEs, and complex pre/postconditions which can't easily be programmatically checked.
See also: Code Conventions
Thy code shalt be readable! I mean it!
"Performance considerations" isn't a valid excuse to not write readable code unless:
- There's really no other way to do it
- Performance actually matters here (you profiled it multiple times)
- There's actually a notable performance gain here (you profiled it multiple times)
- You've profiled your code multiple times
- You checked multiple times with other people that there's really no other way to do it
- You comment it extensively
- See above
