I believe that to accelerate the delivery of software it's worth it to spend time making the code understandable and well factored. It must be understandable because otherwise no one else, including the author himself after some time, can alter the code base efficiently and safely. Well factored because, in addition to the understandability benefits, without it changes within code in one place will cause defects in other areas.
To make sure these qualities are present in the code I strongly advocate the use of a coding standard, automatically syntax checking code, automated testing and human reviewing of code.
Understandability and design
I've sometimes had two statements, of which the first one must always be executed before the second one. I've added a comment above them saying: "NOTE Sequential dependency! The foo must be run before bar!" I've looked at the comment for a few seconds before realizing that there's no reason to leave it that way, and promptly extracted the two statements into one method, which handles the dependency.
I have also made changes to procedural programs while trying to be non-intrusive, yet found that the new behavior has affected areas far and wide in the program. After refactoring the messy code I have been amazed with the simplicity of the actual control flow and the short time it takes to refactor (and automatic tools expedite this even further). Making changes to resulting well factored programs have usually been trivial and seldom affected other areas of the application.
Coding standard
Adhering to a coding standard takes some time but pays back generously. Defects are exposed more easily with a consistent code base and error-prone ways of programming are prohibited. The only real obstacle to using a standard is a team with members unwilling to abide by a standard.
Automatic syntax checking
This method is often both cheap and already available, e.g. the basic linting feature most programming platforms provide. It saves a little time when errors are noted when coding, but a real boon is the linter reporting syntactically correct but maintainability-wise hazardous syntax.
Of more advanced form is automatic code standard enforcing which might need more configuring, but will further reduce the risks of using dangerous syntax and keeps the code base consistent. It also often shortens the time needed to learn the coding standard.
Automated testing
Automated testing is an excellent way to keep the program in a stable state even when refactoring intrusively and having tests is also priceless when checking for regression bugs.
Furthermore, tests serve as excellent documentation, capturing requirements and communicating the usage of code. And I find test driven development a great way to solve very difficult programming problems.
However, as with all methods, it isn't always useful. Manual testing finds an immense amount of problems with a single glance and I recommend at least some manual checking no matter how many automated tests there are.
Review
Human review has been found in many studies to find defects in software very well and I really like to hear others' opinions of the hard spots of my code. Even in my own solo projects I try to review my own previous work.
Conclusion
I find these qualities and processes to be the default in my own work and I would need a reason to *not* use them. Obviously when a service is down and you're losing money every second you need to go and bring it back up quickly so some of these practices can be skipped, at least temporarily. I sometimes restore service by making a change directly to the production bypassing even version control and deployment, but immeadiately start work on a proper fix. After the production is stabilized there's less time pressure but when using methods like this it must be communicated well.
Another good reason to skip some of the aforementioned practices is a new technology which has no support for the practices or a tiny project which would not justify the overhead. Even the dreaded rush to forget the process and deploy fast can sometimes be justified, but you have to be careful when judging it.
There are other requirements of good code e.g. security, performance and scalability, but the level at which each of these should be implemented vary among projects. If in doubt and forced to choose, I'd make the program more secure, more performant and more scalable, rather than less, but I'd be careful not to overdo it.
Here is an example, albeit a small one, of a project with reasonably good code quality.
Excellent books I've read about programming
To make sure these qualities are present in the code I strongly advocate the use of a coding standard, automatically syntax checking code, automated testing and human reviewing of code.
Understandability and design
I've sometimes had two statements, of which the first one must always be executed before the second one. I've added a comment above them saying: "NOTE Sequential dependency! The foo must be run before bar!" I've looked at the comment for a few seconds before realizing that there's no reason to leave it that way, and promptly extracted the two statements into one method, which handles the dependency.
I have also made changes to procedural programs while trying to be non-intrusive, yet found that the new behavior has affected areas far and wide in the program. After refactoring the messy code I have been amazed with the simplicity of the actual control flow and the short time it takes to refactor (and automatic tools expedite this even further). Making changes to resulting well factored programs have usually been trivial and seldom affected other areas of the application.
Coding standard
Adhering to a coding standard takes some time but pays back generously. Defects are exposed more easily with a consistent code base and error-prone ways of programming are prohibited. The only real obstacle to using a standard is a team with members unwilling to abide by a standard.
Automatic syntax checking
This method is often both cheap and already available, e.g. the basic linting feature most programming platforms provide. It saves a little time when errors are noted when coding, but a real boon is the linter reporting syntactically correct but maintainability-wise hazardous syntax.
Of more advanced form is automatic code standard enforcing which might need more configuring, but will further reduce the risks of using dangerous syntax and keeps the code base consistent. It also often shortens the time needed to learn the coding standard.
Automated testing
Automated testing is an excellent way to keep the program in a stable state even when refactoring intrusively and having tests is also priceless when checking for regression bugs.
Furthermore, tests serve as excellent documentation, capturing requirements and communicating the usage of code. And I find test driven development a great way to solve very difficult programming problems.
However, as with all methods, it isn't always useful. Manual testing finds an immense amount of problems with a single glance and I recommend at least some manual checking no matter how many automated tests there are.
Review
Human review has been found in many studies to find defects in software very well and I really like to hear others' opinions of the hard spots of my code. Even in my own solo projects I try to review my own previous work.
Conclusion
I find these qualities and processes to be the default in my own work and I would need a reason to *not* use them. Obviously when a service is down and you're losing money every second you need to go and bring it back up quickly so some of these practices can be skipped, at least temporarily. I sometimes restore service by making a change directly to the production bypassing even version control and deployment, but immeadiately start work on a proper fix. After the production is stabilized there's less time pressure but when using methods like this it must be communicated well.
Another good reason to skip some of the aforementioned practices is a new technology which has no support for the practices or a tiny project which would not justify the overhead. Even the dreaded rush to forget the process and deploy fast can sometimes be justified, but you have to be careful when judging it.
There are other requirements of good code e.g. security, performance and scalability, but the level at which each of these should be implemented vary among projects. If in doubt and forced to choose, I'd make the program more secure, more performant and more scalable, rather than less, but I'd be careful not to overdo it.
Here is an example, albeit a small one, of a project with reasonably good code quality.
Excellent books I've read about programming
