Good code is our best documentation.

Hi Habr! I bring to your attention a free translation of the article " Good code is its own best documentation " from Amit Shekhar .



Good code, like a good joke - requires no explanation.

If your code is simple and clear, then for the most part, it does not need comments and documentation.

A good code is like a car with excellent stereo and cup holders, which without any problems accelerates to the limit. When it breaks, any mechanic can fix it in a short time using conventional tools.

The bad code is like a car that promises to be able to reach 120 km / h, but has a stereo that only accepts cassette tapes, and cup holders have sloping bottoms. Each time you try to set up mirrors, the car explodes in a flame and needs to be repaired by the specific person who assembled it on the assembly line using its unique tools.

Good code is like a well written tutorial

• Simple and clear
• Conveniently divided into chapters, each of which is devoted to a clearly defined topic.

Bad code is like a badly written tutorial

• All chapters refer to each other, and it is not clear what is at stake
• One and the same story is told again and again, and for no reason
• The author mentions several exceptions to the rules, while often contradicting himself
• A vampire suddenly appears! He sparkles in the sun

This is important to remember if you want to write good code:

• Visibility - for you and anyone who decides to look into your code
• Support Ability - Your Code Must Be Easily Modifiable
• Simplicity - do not complicate everything for no reason
• Efficiency - Your code should work as fast as possible
• Understandability - if your code is simple and understandable, in most cases no comments are required at all. Choose such names of properties and methods so that it is immediately clear what he is doing.
• A low ratio of perturbations to surprised exclamations per minute minimizes the frequency with which another developer will read your code and say “WTF ?!”

Code Quality Check

Show your code to another programmer who has not seen it yet, and let him try to explain what each module does, and listen carefully.

The more you want to interrupt and explain in your own way, the more likely your code is worse.

If you can calmly and silently listen, and the person next to you explains everything and does not ask questions, perhaps your code is good.

Signs of good code:

• He looks smart but not abstruse.
• You can return to writing code after the weekend, and immediately get to work without rethinking what was written
• The algorithms are optimal in speed and readability.
• Classes, variables and functions are named so that you do not need to strain the brain to understand why they are needed
• Each of your classes is for one clearly defined purpose, and is separate from other classes.
• Your methods are short - ideally shorter than 50 lines, and certainly not more than 100
• Methods are for one task.
• The names of the methods uniquely determine what they do, and you do not need to look at the code inside this method
• If you need to go back and add / modify some function, this should not cause difficulties
• Your try / catch blocks are as small as possible.
• Unit tests are easy to write and effortless.

Good code is modular

Let's say your project has three layers - internal, medium, and external.

Your inner layer should not know anything about your middle or outer layer. Your middle layer should not know anything about your outer layer.

Thus, your inner code layer can be tested independently.

Read more about this in this article ( Translator Link )

“Good code is our best documentation” - Steve McConnell