Good code is our best documentation.

Hi Habr! I offer you a free translation of the article " Good code is its own best documentation " by Amit Shekhar .



Good code, like a good joke - does not require explanations.

If your code is simple and straightforward, 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 accelerates to the limit without any problems. When it breaks, any mechanic can fix it in a short time using ordinary tools.

Bad code is similar to a car that promises to be able to reach 120 km / h, but has a stereo that only accepts cassette tapes, and coasters have sloping bottoms. Every time you try to adjust the mirrors, the car explodes in a flame and needs to be repaired by a specific person who assembled it on the assembly line using its unique tools.

Good code is like a well written tutorial.

• Simple and straightforward
• Conveniently divided into chapters, each of which is devoted to a well-defined topic.

Bad code looks like a badly written textbook.

• All chapters refer to each other, and it is not clear what they are talking about.
• Again and again it is told about the same thing, and there are no reasons for it.
• The author mentions several exceptions to the rules, and often contradicts himself.
• A vampire suddenly appears! He sparkles in the sun

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

• Visibility - for you and everyone who decides to look into your code
• Support capability - your code should be easily modifiable.
• Simplicity - you shouldn't complicate everything for no reason
• Efficiency - your code should work as fast as possible
• Understandable - if your code is simple and straightforward, in most cases no comment is required at all. Choose the names of properties and methods so that it is immediately clear what he is doing.
• The low ratio of disturbances and surprised cries 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 yet seen it, and let it 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 listen quietly and silently, 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 go back to writing code after the weekend, and get to work right away without rethinking what is written.
• Algorithms are optimal for speed and readability.
• Classes, variables and functions are named so that you don’t need to strain your brain to understand why they are needed.
• Each of your classes is for one, clearly stated goal, and separated from other classes.
• Your methods are short - ideally shorter than 50 lines, and certainly not more than 100
• Methods are designed to perform a single task.
• Method names uniquely define what they do, and you do not need to look at the code inside this method.
• If you need to return and add / modify any function, it should not be difficult.
• Your try / catch blocks are as small as possible.
• Unit tests are written easily and effortlessly.

Good code is modular

Suppose there are three layers in your project - inner, middle and outer.

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

In this way, your inner code layer can be tested independently.

Read more about this in this article ( Link translator )

“Good code is our best documentation” - Steve McConnell