Going crazy coding
By Andrew Smith
Introduction
Are you ripping your hair out because you have no idea how to make the next step in your programming project? Are you modifying someone else's code? Are you wondering whether you chose the right career? This page is for you!
Are you blaming someone else for your troubles? In that case this page my not be for you but read on anyway...
Symptoms
You've been working on (or rather, you have been stuck at) a relatively insignificant problem for at least the last few days, but maybe even a couple of weeks. The complexity is overwhelming. Every day you start fresh, discovering more about the environment where your probem lives but as the day goes on you get lost in the endless chain of function calls, macros, and all kinds of other abstractions.
By the end of each day you are ready to give up. If you've worked on such complex problems before, you know that it's probably just a matter of time. If this is one of your first you're ready to cry.
Maybe you think you're a genius and maybe not, but you sure as hell know you're not stupid. Yet you can't make sense of this code. Someone wrote it. Someone else modified it, someone added features or fixed bugs. You're wondering whether they all have a talent or something, something you don't have.
You're wondering whether you can make it in this business. What if this something others have that you don't cannot be acquired over time? What if no kind of experience or hard work will get you to their level? Perhaps the people you're thinking of are even younger or less experienced than you. These thoughts depress you even more.
Causes
First of all let me tell you a secret: there is no such thing as a talent for programming. A good programmer is defined by a set of highly specialised skills. That's skills, not talent. I've heard stories about people who were programming when they were 5 years old. Yeah, sure.
Yes, some people acquire these skills faster than others. But that's not so much of a big deal. And once you get the hang of it, it won't make any difference.
There are many reasons why you're in this mess. All of them have to do with the people who wrote the code you're modifying. Here's a single-sentence summary I will expand below: It's so hard because the people who made it followed rules. I use the term rule to describe things like formal and informal design, habits, copying and compliance.
Cause 1: formal design
This one is the worst. Formal design results in pointless, absolute rules. It's created by people with good intentions, who honestly try to solve the problem of maintainability of large codebases. Unfortunately they are by definition too generic to be of any use.
The instinct to formalise the process of coding is there in many of us. After all it's true that we solve the same problems in roughly the same way over and over again. We should be able to make a set of rules to help newcommers solve these problems with less effort. In the early 90s such rules have been called design patterns and started to be formalised and published, making managers around the world very happy. Soon after patterns were taught in schools and adopted in all kinds of mismanaged organisations.
You see complex problems are never solved in exactly the same way. The design fan may draw a diagram of a process and fit any collection of code into that template, but the similarity is an illusion. Quite simply: the problems we solve when doing serious programming have so many dimensions there's no way to represent them on a piece of paper.
In this regard programming is like any other kind of engineering. A structural engineer can draw something on a piece of paper that to you will look like a building, but you won't try to build it with just that piece of paper, and you won't take the details from another project to fill in the blanks of the overview you got. It's not quite that simple, is it?
One of the programmer's acquired skills is the ability to understand how real code works. Patterns in programming do exist, and an experienced programmer will see them subconsciously. But when patterns are faked, to follow a formal design, the complexity of the code is doubled, with the real solution wrapped in a fictitious one.
Cause 2: informal design
This is basically the same as formal design except the perpetrators are not managers but the coders themselves. I don't know why they would do this to themselves, but I suspect an abundance of idealism and an inability to acknowledge failure are the main reasons.
Cause 3: habits
This is a more passive cause, habits are a failure to make an effort to write readable code.
The problem is that having done something in a certain way for a long time a programmer will solve a new problem using the solutions he used before. What's wrong with that, you ask? Well, those solutions may be inadequate not only in performance but also in readability.
The most readable code is obvious. Obvious not only to people who have been writing code like that for years but also to a newcommer who understands the problem (and the terminology of the domain) but has never worked on a solution before. It's very easy to write unreadable code. It's also surprisingly easy to write readable code.
Uncontrolled habits can have a detrimental effect on readability. Instead of calling functions/variables after what thy really do/are the programmer tends to call them after functions and variables from a somewhat (but really not) related piece of code he's worked on before. Same with the structure of the code. If the programmer is used to working on horrible 5-instructions-per-line code he will end up writing code like that because the complexity no longer jumps at him - he's used to it.
Cause 4: compliance
This may be the only cause of your headaches presented here that for many projects is practically unfixable. Compliance is among the programming practices that increase readability. If all the code has the same structure, and you have experience with part of the code - you will pick up another part easier. The problem is that if the code you're adding to is not readable and you follow its structure, the stuff you write is equally unreadable.
It takes a significant effort to write in a different style than the base of what you're contributing to and the result may not be positive, since the lack of consistency may prove to be a bigger readability problem than whatever caused the inconsistency. On top of that your code has to be accepted by the maintainers of the base - and they may make you unhappy about your effort or outright refuse to accept your addition.
Solutions
First and foremost - the solution: don't blame yourself, blame the people responsible for adding complexity to the code for stupid reasons such as design principles, corporate policies and carelessness. If you succeed in convincing yourself they are the reason for your pain, you will feel better. The rest of this section is advice on how not to become one of those people at fault.
Don't do design for the sake of design. When you read some code and it looks well-designed, remember you can only guess why it is so clean. It's a natural assumption that something straighforward and beautiful was designed first - after all a structural engineer only gets one shot at getting it right for a building that looks good, but we are not that kind of engineer! Our job is infinitely more complex and seing an entire solution in your mind is plain impossible for non-trivial problems. We do it one way, maybe try another way, and keep improving on working code, code with a growing number of potential uses and all kinds of dependencies. Code that you look at now may have been partially or completely rewritten several times. Things could have been renamed, classes merged and split up, functions made public or private, ad so on. It's all nice and neat now - but have you seen it while it was being developed?
Put a bit of effort into making sure your code is readable by people other than yourself. Just think back about when you had to work on some code with constructs you have never encountered, that's the audience for your work. Of course there's no reason to write 'stupid simple' code either, but just thinking and caring about it will make it better.
Finally, if you're truly bold, you can deal with compliance. Solutions are all difficult and range from fixing all of the code you're working on to just making your addition inconsistent with the uglyness and insisting it's still better.
Overall, you can make a big difference in the accesibility of your code by making small efforts here and there. You can go to the extreme of course but that's not required. And when you're spitting blood, thinking of ways to murder the author of the code you can't understand at least you'll have the satisfaction of knowing noone is thinking of murdering you.
To complain about this writing send me email