The Simple Path to Worthy Code
- Start by identifying an actual problem that needs a solution. It is important that you have an answer to the question “Why is this a problem”. A problem is not necessarily a bug; your users need new features to solve the problems they have. Focus on just one problem at a time and do not attempt to solve many problems at once. Think of all the possible system outcomes that can make the problem go away. There are usually many and some problems can be solved without code.
- If you think code is needed, outline a solution in your mind. You can use pseudocode here. There are many approaches to solving a problem. Find the approach that makes the most sense. Do not stop after coming up with just one approach. Always ask yourself, is there a better approach?
- Once satisfied with the approach in mind, write any code to implement that solution, no matter how ugly that code is.
- Verify that the code you wrote implements the solution that you outlined. You can write code to do so; we call that automated testing.
- In some situations, it pays to change the order of 3 and 4. We call that TDD.
- If your code has to modify or integrate with other code, just make sure that you do not make that other code worse to fit your new code. You can improve that other code if you can afford the time and only if you can test your improvements (if the other code does not have automated tests, start by adding some).
- Take a deep look at the code you wrote to implement the solution and identify all the problems that you can find with it. Get help on this if you can. We call that peer review.
- You can probably ignore most of the problems you identify on that list unless the type of the problem is: A) Readability, or B) Efficiency.
- Act on type A above. Code that is hard to read is simply worthless. Be declarative if you can, minimize any new API you introduce, eliminate hard-coded values, and try to use composition if possible. Generally, avoid using comments to explain code. If the code needs comments to be clear, that is your sign that you can make it more readable. Iterate until you are happy with the readability of your code. Readability will eventually make your code more maintainable and extendable.
- Get others’ opinions on the readability of the code and iterate until they are happy with it. Your code is only readable if others say so.
- For type B above (Efficiency), answer the following question: Will your code be executed often? Will it be used by a lot of users (including machines using your code on behalf of users)?
- If you answer no to the above questions, you should probably do nothing about the type B problem that you identified. Your time is better used by solving more problems.
- If you answer yes, find a way to measure the suspected efficiency problem in the code. Account for all resources (processing, memory, network, …etc). Do not proceed until you have valid and consistent measures here.
- Modify the code and validate that the measured quantities above are better with your modifications.
- Make sure that the verifications of the implemented solution (in step 4 above) are all still valid after all the changes.
Thanks for reading.