When you are coding a project for your client, yourself or reviewing project written by someone else it is very useful to have some metrics by which you can judge if the project is done well or not.
In this article, we will focus on three main qualities every solid project should have: correctness, performance and maintainability. We can imagine the characteristics as blocks of a pyramid where at the base is the most critical quality and at the top are nice to have things. You cannot add a block on the top unless you have a solid base.
However, programming and project management is definitely not just that simple. Sometimes, we have to do compromises even in the most critical parts of the program because otherwise, the project would not be feasible. The point is we should not do this mindlessly. If we ever compromise on any quality, we should always know the pros and cons. Be it cost, delivery time or technical complexity.
Let's now discuss the three characteristic which you should focus on first. We will evaluate them in the order from the most important to the least important.
If the code is not doing what it should, it is worthless. The main goal of the solution is to actually solve some problem. The main prerequisite of correct program is to have clear and detailed specification which the developer can follow almost like a cooking recipe. The specification should not be set in stone, it needs to be a living document that is flexible enough so it doesn't prevent achieving these 3 goals. Sometimes even small change in the specification can lead to big increase in any of the 3 main parameters. That is why a constant feedback between the developer and the client is so important.
What are the key parameters of correct program?
- Performs tasks that it should perform. No less, no more.
- Outputs data in a correct format.
- Is resilient.
Check the debugging section to learn how to deal with correctness issues.
The second most important characteristics is how efficient and fast the program is. Good program should be fast and cost-effective. When running actors on Apify, the performance is directly exposed as consumption of Compute units. The performance is directly proportional to how much you pay. Even before you start writing the code, you should evaluate different possibilities and technologies you can use. You should choose the most performant one that can still fit the specification. And as discussed previously, the specification should allow a small change that can allow the program to be 3 times faster/cheaper. Of course, there is a limit to this idea as we have to also add other important qualities to the equation: How maintainable the solution will be? How long it will take to develop it? These are the main reasons we don't code in machine code anymore even it is the fastest code we can write.
What are the key parameters of performant program?
- Uses the most cost-effective technology that can do the job and is still maintainable.
- Doesn't do any unnecessary work.
Check the performance section to learn how to make your actors faster and cheaper.
Unless you are writing extremely simple one-time project, there is a big chance that the project will need to be fixed, enhanced or even reviewed by other people. If you ever had to work with horrible code, you know how painful experience it is. And what if you want to make substantial fixes or changes of such program? Then it is usually the best to just rewrite it completely. If you do so, the hours (and dollars) spent by the previous develop are lost.
Writing high quality code is sometimes viewed as a cherry on a cake and it is also impossible for non-developer to evaluate it. You can get away with sub-optimal code-base with smaller projects where speed of delivery and cost are primary. But in bigger long-term projects you have to invest into code quality and make sure the developers follow a common standard.
What are the key parameters of maintainable code?
- Any developer can easily read and understand the code
- Variables are well named
- Code comments help to understand decisions
- Actor has a clear input/interface
- New functionality can be easily added