The 1/10th Rule: When passing software code to others, strive to pass comprehension to others in 1/10th of the time it would have taken you to learn it without any guidance.
Programming isn’t an easy job (although for some it might be). A critical moment in time in any software project is when a 3rd party comes to look at your code.
Imagine yourself as a complete beginner working on a new software project. You are willing to learn but have no idea where to start. The project seems so large! I asked a couple of experts and each tell me to start in a different place and learn that thoroughly. But it feels like trying to understand the mechanics of a car by first studying axels in depth, then wheels in depth, and so on. This could eventually lead to understanding how a car as a whole works but that’ll take time. The introductory document explains stuff in a hand waving fashion but it doesn’t allow me to sink in enough to understand what’s happening. argh!
This is where effective documentation and code commenting helps (and the 1/10th rule comes in). Say you spent 10 hours making that perfect algorithm to solve some problem. So you code it up and in it goes. You spent 10 hours and know it perfectly. You leave a comment here or there saying (clean memory!) but don’t explain your intentions about why you wrote this. The next person that comes along now has to stare at your code for another 10 hours just to understand what you wrote. But perhaps they get sick of this and decide to just write their own version and replace it. A few more comments so they can understand what you meant in an hour would have helped immensely! When it comes time to explain something think very hard about how you can reduce the next person’s mental burden to 1/10th.
When writing comments in my code I try to carry this rule out. I’m not sure how well I follow it but I think it’s an ideal to strive for.
