I’ve recently had the opportunity to work with a large, unfamiliar code-base. The experience has made me reflect on some of my own coding practices and on writing more maintainable code. Much has been written on this topic, but here are the things that I feel are most important and have a high payoff without much (if any) additional work.
Make use of inherent metadata
Programming languages have inherent metadata in how you name things, what types you use, scoping, visibility, etc. This information is invaluable for someone new looking at the code and helps make the code self-documenting. There are several things you can do here:
Use good names
- Give classes, variables, methods, functions, etc. descriptive, differentiable names. Things that are related should have similar names, while things that are not should not.
- Keep the names up-to-date. If functionality changes, update the name.
- Variables with different scopes should be differentiated. For example, prefix instance variables with an underscore.
- Be consistent.
- Don’t create variables for things you only use once – just put them inline. Then I don’t have to figure out where else the variable is used.
Use appropriate types
- If possible, don’t use multi-level typedefs. It’s a real pain in the ass to go through 5 header files to figure out that foo_bar is an unsigned integer. And don’t typedef pointers away – I want to know if something is a pointer or not. Especially don’t typedef pointers away by inventing your own syntax (e.g. CFArrayRef is a CFArray pointer). The language already has syntax for that.
- Do use typedefs for things like enums.
- Use the most-specific type possible. If something should not be negative, make it unsigned, etc.
Use appropriate visibility
If something should only be used within a class, make it private. People looking at the code then don’t need to worry about external clients.
Keep things short
Nothing is more depressing than trying to grok a long method/function/class. There shouldn’t be hard rules on length, but I try to write methods/functions that fit on one screen, and to keep my classes under around 1000 lines of code. Without caution, this can lead to a method/class explosion, but I’d rather grok a small class cluster than one gigantic class.
Keep block nesting to a minimum
Don’t have a while loop inside an if, inside an else, inside a for loop, inside an else if, inside an do/while loop, inside a …
Reduce coupling
If I have to understand more than a small portion of the code to change one class, there is a problem.
Write useful documentation
You don’t need a lot. Here is what I think is important:
- Describe briefly what a method/function does. No method or function should be so complicated that this is more than a sentence or two.
- If a method is overriding a superclass, note that and explain why.
- Explain anything unusual or complicated.
- If a method has concurrency issues (should only run on the main thread, etc), note those.
Think of those that come after you
Whenever you write some code, try to put yourself in the shoes of the next programmer to work on the code. This is the programmer’s version of the seven generations rule.
