OK, so this video’s a bit cheeky, but it does deliver a salient point. Some programs and code I have had to work with were written by people who clearly did not know when to stop. I’d like to think that really this is the fault of the inexperienced, but it is probably also due to programming arrogance. Some people just cannot stop gilding the lily. On the rare occasion anyone else is looking at your code, make sure they can work with it!

  1. Don’t comment it to death, I’m a programmer, it’s my job to be able to read and understand code. If you must comment then write about the objective the code is trying to achieve, or if there are any particularly cryptic sequences, explain them. DO NOT comment things that are obvious.
  2. Keep the code clear. Showing you know how to use every tool in the toolbox does not lead to clear or particularly clever code. Make every effort to keep your source code as compact and minimal as possible. Don’t be afraid of using constants in your code. Sometimes 3.14159 is clearer than M_PI.
  3. Dont assume that auto-documenting your code is sufficient, in fact tools like doxygen can often make code harder to read and write, and in reality provide little benefit if you’re not fully committed to it. If your code base is spanning many files, then sure, a tree can help understand it.
  4. The best documentation ever is a little additional program that shows how your code should be used. Focus on that rather than trying to write examples and usage syntax in header files.
  5. Write good code! Well duh… but if your code works, and is obvious to use, and you provide an example, then I’ll never need to examine it will I?

Anyway – behold the acting!

Happy Coding,