Good code is its own best documentation

4e185 1ip0pzufq3pq7ktuv0nz7fq

Good code is like a good joke — it requires no explanation.

If your code is self-explanatory, there’s no need for comments and documentations, most of the time.

Good code is like a car with a great stereo and cupholders, that reaches the speed limit with no problems. When it breaks, any mechanic can push it into their garage and fix it up in short order, using common tools.

Bad code is like a car that promises to be able to reach 200MPH, but has a stereo that only accepts cassette tapes and the cupholders have tilted bottoms. Any time you try to adjust the mirrors, the car bursts into flames and has to be repaired by the exact person who put it together on the assembly line, using alien-looking tools.

Good Code is like a well written textbook.

  • Easy to understand
  • Nicely divided into chapters that each make distinct points

Bad Code is like a poorly written text book.

  • All the chapters reference one another, but it’s unclear what each chapter is about
  • The same thing is described over and over again, for no apparent reason
  • The author mentions several exceptions to the rules, and frequently contradicts themselves
  • Suddenly there’s a vampire! It sparkles in the sunlight.

Things you should keep in mind if you want to write good code:

  • Readability — for you and anyone else who has look into your code
  • Maintainability — keeping your code easy to modify
  • Simplicity — not introducing unnecessary over-complications
  • Efficiency — your code should run as fast as you can practically make it
  • Clarity — if your code is self-explanatory, there’s no need for comments most of the time. Name your methods and properties sensibly. Break long code down into smaller bits. And never copy & paste a block of code. Comments and documentations are much needed when we required it. As code comment is a piece of human-readable text that is written in the source to explain why some piece of code exists.
  • Low WTF?!s per min ratio — minimize the frequency with which another developer would read your code and say “WTF?!”

The code quality test

Have another programmer who has never seen your code read it and explain what each module does to you while you look over their shoulder.

The stronger your urge to jump in and explain something, the worse your code likely is.

If you can calmly sit there with your mouth shut, and they don’t need to ask a lot of questions, the code you’ve written is probably good.

You know you’re writing good code when:

  • Things are clever, but not too clever
  • Algorithms are optimal, both in speed and in readability
  • Classes, variables, and functions are well-named and make sense without much additional thought
  • You come back to your code after a weekend off, and can jump straight back in
  • Things that will be reused are reusable
  • Methods tend to be very short and ideally perform a single task
  • You have enough information to call methods without looking at the code inside them
  • When your each class serve a single, very clearly defined purpose, separated from other classes with other clearly defined purposes
  • When your methods are short — ideally under 50 lines and certainly under 100 — and their names clearly define what they do exactly
  • When we have to go back and add/modify a feature, it should be easy
  • Your try/catch blocks are as small as possible
  • Unit tests are effortless to write

Good code is modular

Let say you have three different layers in your project — inner, middle, and outer.

Your inner layer should not import anything from your middle or outer layer. Your middle layer should not import anything from your outer layer.

This way, your inner layers of code can be tested independently.

For more about this, read this article.

“Good code is its own best documentation” — Steve McConnell

You can connect with me here.

Also, Let’s become friends on Twitter, Linkedin, Github, and Facebook.