“Steam-of-Consciousness-Dumping” Coding Style

In this article I describe one of the most popular coding “anti-pattern” which causes a lot of headache for all project team.

This post is not related to Perpetuum Software products. Moreover I hope nobody believe that we use the style described in this article when creating our products . However we in Perpetuum Software use some techniques to avoid some serious issues in coding style. I’d like to share them with you.

I hope that you can recognize the most valuable part of this article (to my mind of course): all developers should be taught a good coding style before they became a professionals. And the project manager or the team lead is responsible for this process.

So, let’s start!

Steam-of-Consciousness-Dumping

Let’s imagine a developer has a task to write a new module or add some functionality to an existing system. What a mature developer will do? He will make a cup of China tea, sit back, take a pencil and start thinking. He will draw module structure, carefully consider entities, interfaces and their interactions, move down to specific methods and probably write unit tests for interfaces. Only then he will start filling the structure with the code (if he will not decide not delegate the task to outsourcers).

And what a junior will do? “Since there is a task, there must be the solution’’ – this is what they are taught in Colleges and Universities. Many of them are still under strong influence of the marginal motto: “Programming, Mothe####ker!”. So, he makes a cup of instant coffee, takes on headphones with some hardcore music and leaves this world for couple of hours.

And this would be ok … I have nothing against instant coffee, headphones or flow state. Moreover, it is often the most effective and even the only way to write good code. But we consider another case here: typical new-born developer, so let’s have a look at his results.

What we see in the end

First of all, the functionality is implemented. It works in most cases and looks pretty satisfactory. The first thing you wanna do is to cheer that a new specialist has completed the task so fast, compliment him and give him more jobs. But try to look into the code and it will become obvious why it was done so fast. And here the scary part begins…

You see the code that I usually call as ‘dump of stream of consciousness’. I call it this way because the code is being written as a single block without any attempts to comprehend it, come back and change something. Below, I’d like to list its main characteristics.

First of all, the code is usually just one and a very long method. It can sequentially do the following: initialize the connection to a database, build a SQL query, get data and process them and (let it be a web developer) create HTML for final view. Author is writing about the things he is thinking about in the moment, he is in the flow and focused on the task solution. His consciousness solves the task step by step and these steps are immediately reflected in the code.

Second, the code is usually overflowed with commented lines and huge but needless parts of codes which he does not dare to delete.

Third, such code usually handles only the main usage scenarios and standard conditions. Slightest deviation from normal user behavior causes malfunctioning and unhandled exceptions.

Why it’s bad

I already mentioned some disadvantages above, but there are more things to say.
The worst evil of this code is impossibility of its maintenance. Indeed, in couple of days not only other developer, but even the author of the code will be unable to understand what is going on inside that code part and what that branch means. It becomes obvious that developers, including the author will further maintain this code not only reluctantly but extremely ineffectively.

Moreover, it will affect the project goals, delaying deliverables and lowing quality making the Project Manager really upset. Work with such code will tear down team motivation depriving a developer of two the most liked sides of his work: “I am doing something cool and needed” and “I am doing my job great”

One more painful part of the “stream of consciousness dumping” is that you don’t see these problems from the first sight, because “it works”. Testing of such code (that is ‘black box testing’ for sure) is often really complicated: a tester faces bugs which are highly difficult to reproduce. They usually occur because of the interlaced and completely unstructured mass of calls and related tacit bridging when one part of code affects another one in absolutely remarkable manner.

Thus, the “pool of victims” now gets a tester – one more suffering part in addition to a developer and project manager. And to finish with the project team, we add 2 more people there: a product manager (or a customer, if it’s a custom development project) who will never have an ability to effectively add new features to the product and an analyst, who will never have any idea what it takes to bring even minor changes to the product functionality and will have to listen to unrepeatable speech from developers after asking them to slightly update the work of a search screen.

The conclusion is simple – “dumping” is an evil to fight against.

Not to talk just about theories, let me share with you experience of such “fighting against dumping” I use in our company.

How do we fight against?

Foremost you should understand when you see such code – “it’s normal”.

If you have not yet started your fight against “dumping” and your predecessor has never done this as well, your team will have the developers which use such approach and sincerely believe that it’s right.

The new-comers who joined your team right after graduating the University are likely to exploit “dumping” as well.

And this is normal behavior of yesterday’s student who has a task and must solve it. He sees the goal: implement the required feature, but he does not understand that by creating bad code does not make him hit the goal, but makes it hardly reachable.

So, the first thing we need to do to fight against “dumping” is to set up regular code inspections.

If your team has a good specialist who understands “spirit and letter” of good architecture, right decomposition, transparent code and other decencies, the first inspections must be his task.

At the same time, he (as a responsible party) and you (as a manager) need to understand that the main goal of inspections is not to ‘give the works’ to a slack coder, but to teach him coding the right way and promote a love to pretty code and architecture.

If your team includes only new-comers and you don’t have such a specialist, you will need to raise him.

Code improvement is always better to start from separating big and sometimes huge methods into small and neat ones. Usually it is enough to ask your developer what that part of code does step by step and then bring these steps into separate methods. Then, you need to separate each method using the same approach (so called recursion, you know) till the meaning of each of them becomes simple and clear. By the way, I intend to describe the recurring approach in one of my next articles.

Besides, you can lay down a rule: “do not write methods longer than 20 lines” and don’t forget to check it on regular inspections. This way a developer will always think on how to divide its “dumping” not to break the rules. Of course as any rule, it cannot be treated like a dogma. I can easily imagine a method that can take more than 20 lines to describe it. But anyway, a developer will always remember rule and the coding process will be much more meaningful.

Following the same approach you can teach a developer dividing a class into several ones organizing them as layers, modules, and so on and so forth.

But this is a different ball game… And now a developer surprisingly stares at you and cannot understand why you don’t like so much his wonderful method which took 2 days of his hard work and which “makes everything work”.

So, explain this to him!

You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.