So make it easy for other people to read

What is code for? If you think its just to solve a problem you may have missed something.

There is a problem in the name "code". If what developers do is "coded" in some sense — i.e. not immediately obvious to the reader — then there is significant danger that anyone reading the code will misunderstand it, and that includes the author of the code themselves.

Code exists primarily to convey a technical solution to other people's minds. If it fails to do that then it is poor and potentially dangerous code.

The main implications of this are:

  1. The application code and the test code work together, so it must be just as easy to understand the application code as the test code. That means that you should apply professional best practice to ALL code, ALL of the time.
  2. Use all means possible to clearly convey the intent of what you are trying to do to the reader. This includes using comments and docblocks. In fact it is impossible to convey intent without using comments. This is why some otherwise "Clean Code" is so difficult to work with: you can see clearly what it does but you have no idea what it was intended to do.
  3. Under NO CIRCUMSTANCE should you leave any doubt as to your intent in the minds of the reader of the code.
  4. Non-technical people should be able to read your code and have a clear idea of what it does. The best programmers ask non-programmers to read their code. If non-programmers can not understand it, programmers will struggle too.

Test code is code ⇒ test code is first-class code

Your test code should always be of the same quality as any other code. It should be easy to understand with good naming that describes the behaviour of the system under test.

Summary

  • You never hear a concert violinist scratching out a tune. Make it your professional practice to always produce your best work, which feeds your intent clearly into the reader's mind
  • Code tends to be write-optimised — but it must be read-optimised
  • Write-optimised code is the result of poor professional practice and is a nest of technical debt and future problems