Perfect code and real projects: part 1

Andrey Akinshin

I’ve got a problem. I am a perfectionist. I like perfect code. This is not only the correct way to develop applications but also the real proficiency. I enjoy reading a good listing not less than reading a good book. Developing architecture of a big project is no simpler than designing architecture of a big building. In case the work is good the result is no less beautiful. I am sometimes fascinated by how elegantly the patterns are entwined in the perfect software system. I am delighted by the attention to details when every method is so simple and understandable that can be a classic sample of the perfect code.

But, unfortunately, this splendor is ruined by stern reality and real projects. If we talk about production project, users don’t care how beautiful your code is and how wonderful your architecture is, they care to have a properly working project. But I still think that in any case you need to strive for writing good code, but without getting stuck on this idea. After reading various holy-war discussions related to correct approaches to writing code I noticed a trend: everyone tries to apply the mentioned approaches not to programming in general, but to personal development experience, to their own projects. Many developers don’t understand that good practice is not an absolute rule that should be followed in 100% of scenarios. It’s just an advice on what to do in most cases. You can get a dozen of scenarios where the practice won’t work at all. But it doesn’t mean that the approach is not that good, it’s just used in the wrong environment.

There is another problem: some developers are not that good as they think. I often see the following situation: such developer got some idea (without getting deep into details) in the big article about the perfect code and he started to use it everywhere and the developer’s code became even worse. And then I have to listen to: “they read articles about these approaches and then start writing code in this way”. And what if this is not about the articles? If some programmers use good practices inappropriately it doesn’t mean that good development practices shouldn’t be discussed. Willingness to write correct code is good, but it’s necessary to estimate development skills soberly. There are a lot of maneuvers of stunt flying described for pilots. But it doesn’t mean that every newbie pilot should try to do them all in the very first flight. The same thing is for junior programmers: he doesn’t need to use tens of patterns he got to know after reading the book of GoF in his next project.

But let’s get back to the discussion of the perfect code. Approach to the correct programming depends on many factors: on purpose, terms, team, etc. I’d like to review several types of projects that have absolutely different purposes. Let’s think to what extent the code should be clear and to what extent the architecture should be elaborated in each case. We will see patterns used in some projects that are inappropriate in other projects. Next time when you got outraged by some advice in a development related article, you should first think what purpose an author had. Maybe this is not advice that is bad, and just your project differs from the author’s one. So, let’s start.

Project size

Small projects
For example, there is one man who develops the project for several days. It is some simple utility that solves a small separate task. Most likely it won’t be actively developed and transformed into something big. You can keep in mind all system elements (and even variables) in such projects. You don’t need sophisticated architecture in this project: if you get a task that can be resolved with a two code lines patch, you better do it. Of course, you can spend two days to develop a complicated architecture that will be convenient to use when new simple tasks arise. But there is a nuance: these simple tasks will hardly appear in such a small project while time has been already spent. In this situation, you don’t need to think about writing the perfect code. You shouldn’t write explicitly bad code as well, just do it right.

Medium size projects
Assume we’ve got a team of 5-6 developers and the project for several months. You can’t dabble here; it’s necessary to think over the system and structure the complete code. It’s better to control the amount of workarounds. Developers can spend some time for initial research, analysis and design, but not too much. It’s good if you manage to create an ideal plan for development of the ideal system by the deadline, but it’s even much better to develop not a very ideal but working system. At worst, if everything goes wrong, it’s not that difficult to re-design the whole architecture by all team members (I had to do it for several times, it’s not that horrible). If this is a custom development project, a customer will pay not for the wonderful code, but for working features implemented in time. Don’t forget about it.

Big projects
And now we have dozens of developers and the project will be developed for several years. And here it’s better to think over the architecture carefully from the very beginning. If there is a need for a workaround then maybe it’s better to re-design the architecture on early stages in the way that new features fit into it seamlessly. Every improper line of code written now will turn into great sufferings in a year or two. Read books about clear coding and correct architecture; they contain much advice that will come in handy. You just need to use it correctly, not everywhere. I like a story from the Martin Fowler’s book: Fowler did some consulting for a company that developed quite a big project. The project code was terrible and Fowler insisted on a slight refactoring. In a couple of days, they managed to get rid of half code without any damage to the system functionality. Programmers were very glad, but executives were not that happy since this work didn’t result in new features. The old code worked and its optimization didn’t seem economically viable. That is why further consulting recommendations were not followed by the executives. They forced sooner development of new features without any additional work on the code. In half a year the project was closed as the code became too complicated to maintain.

Project maintenance

Projects without maintenance
Activity that is well known by various freelancers and outsourcers. After the project is delivered you will never remember all this horror hidden under the car hood. Deep in your mind, you hope that they will just use the project and no one will ever review the source code. And this is an acceptable approach, since we are required to provide a working application, but not the perfect code. In the very beginning of the project you can afford designing architecture, writing correct code. But when there is just two days till the deadline and only half of features are implemented, it’s not about lofty matters. It’s allowed to add any workarounds, infringe all imaginable approaches to good code. And this is ok in this case. I don’t say this is good and don’t guide to make it in this way. But this is normal. Here we talk about programming not as about art, here we talk about the project that should be delivered in time and that won’t be maintained. If you start writing everything ideally, you get a risk to exceed the time frame. You will quit on the customer, won’t get money, loose your time and code won’t be demanded by anyone. You should always remember about the purposes.

Maintained projects
And here I would write the good code, get right architecture and clear code. This is such a wonderful feeling when a customer asks you to add some sophisticated feature and you cope with this task in an hour. And this is because new code can be easily added to the project since it is ideally laid on the existing architecture. It’s so easy to work with the existing code base; the code is understandable and easy-to-orientate. And there is another feeling when a customer asks to add some minor feature (the customer is just absolutely sure this is a minor feature and easy to add) and you look at the classes cacophony, try to estimate how many days you would spend on this minor functionality, but for some reason you don’t even want to touch the keyboard. You can’t even look at this code.

Project publicity

In-house projects
You create a project for you or your team and won’t make it public. In this case you are allowed a lot of things. No one makes you digress from your ideals in software development, but if you want to, you can – there is nothing improper. There is no need to create detailed documentation, you can write comments in your native language (if everyone engaged in the project understands it), and some complicated architectural solutions can be explained to your team members orally. I don’t say that you should certainly do it in this way. But if you are in a hurry some good practices can be ignored.

Public projects
Here is an absolutely different situation. Here you need to document your project properly, so that you don’t get hundreds of questions from your customers every day. And you better write comments in English to make it easy for everyone to understand them. If you have an API, you better think over it; don’t add some interface which will allow you to get all necessary data only if you really need to. Remember that the project belongs not only to you, but also to third party developers. Respect those developers who will work with your code. Write code in the way that won’t make others want to stop you in the dark backstreet and hurt you.

The second part of the article will describe other project types and if it is worth writing perfect code in them.