Code for other people, not just for the solution

Most code is write-optimised. The author just wanted to get their story points in the bank, by creating a solution as quickly as possible. They were focusing on the solution. Instead they should have been focusing on the reader.

Program with intent

It is perfectly possible to write code that does not do what you intended or does not correctly address an edge case.

• Good comments are important — you cannot express intent purely in the code: some external source of intent is needed
• Be clear about what your code is going to do
• Say what it is going to do up front
• Choose good file, class, method, and function names
• Use DocBlocks everywhere — the descriptions in DocBlocks are excellent containers for intent. Many IDEs create DocBlocks almost for free
• Write unit tests first — these help to document the intent of your application code
• Consider and explain edge effects

If you don't program with intent your source files are just a stream of your consciousness. Other developers can't read your mind.

More on DocBlocks

DocBlocks are excellent containers for explaining your intent. Use DocBlocks to explain the purpose and context of the source file and the purpose of each class/method along with parameters, return types, exceptions etc.

If you are struggling to name something, start with a comment or DocBlock and include a description of what your intent is, then concertina this into a first attempt at a name, then iterate. Take your time: naming things well is an acquired skill. Remember the name has to communicate your intent clearly to the reader.

Most IDEs help you to create good DocBlocks with minimal effort.

More ways to code for other people

1. Prefer functional programming, but use OO
2. Prefer immutability — structures that don't mutate are easier to reason about
3. Pay particular attention to documenting functional solutions; they can be difficult to read if you are new to functional programming
4. Document complex regular expressions — they are often difficult to understand
5. Log everything — but choose the most appropriate level (if in doubt, log), including timing information for API and IO calls
6. When you think you are finished, and all tests pass, then refactor for readability
7. Review your own PRs before asking for feedback
8. Document APIs using OpenAPI/similar
9. Document significant pieces of work (Epic level)
10. Avoid TODOs, but if they are needed, TODOs must be accompanied by a Jira/ADO reference so we capture the technical debt in Jira/ADO
11. Make sure code is lint-clean (i.e. run ESLint)
12. Apply the Scout principle: "Always leave the code base in a better state than you found it."