In the book The Pragmatic Programmer, the writers mention the “programming by coincidence” concept. It explains what it is, why it is caused, what are the dangers you may encounter and it compares with a landmine field in a war.
Do you ever watch old black-and-white war movies? The weary soldier advances cautiously out of the brush. There’s a clearing ahead: are there any land mines, or is it safe to cross? There aren’t any indications that it’s a minefield—no signs, barbed wire, or craters. The soldier pokes the ground ahead of him with his bayonet and winces, expecting an explosion. There isn’t one. So he proceeds painstakingly through the field for a while, prodding and poking as he goes. Eventually, convinced that the field is safe, he straightens up and marches proudly forward, only to be blown to pieces.
The soldier’s initial probes for mines revealed nothing, but this was merely lucky. He was led to a false conclusion—with disastrous results.
As developers, we also work in minefields. There are hundreds of traps just waiting to catch us each day. Remembering the soldier’s tale, we should be wary of drawing false conclusions. We should avoid programming by coincidence—relying on luck and accidental successes—in favor of programming deliberately.
But I am not really satisfied on the way they describe the “how to overcome it” issue. Yeah, you have to think ahead before writing the code, but how to practice that? The only thing I can think is by adding features to existing Open source projects, where you must have knowledge on both the “what I am doing now” and the “How the other pieces of code are working”, and it is not that applicable when you are writing your own projects.
4
You don’t have to think ahead, merely be very clear on what was done, and be very clear on what you are doing right now.
Subroutines should say what they do, do what they say, and not have hidden dependencies. Then someone calling them can more easily reason about what they will do.
Avoid global state. (Variables, singletons, etc.) The more state that you have to have in your head to understand what things do, the harder it is to understand what is supposed to happen and find the edge cases.
Write unit tests. Unit tests are great for capturing the actual behavior of code that you just wrote, rather than the ideal behavior that you are hoping to find.
Shorten your edit/compile/test cycle. When you add a large chunk of code and test poorly, then the odds are that it will behave differently than you think. Then you “fix” it with some random change, and you got the right answer for the moment, but have no idea how it actually happened. You’re now programming by coincidence. But when you add 5 lines and then test, the odds that you got the right answer because it works like you think it works are much better. I can say from experience that 5 chunks of 10 lines each, individually tested, is a very different beast than 50 lines of code tested all at once.
Refactor ruthlessly. Many times I’ve spotted a refactor that will make my code somewhat simpler but take a bunch of work that I didn’t want to do. After I began deliberately tackling those refactors as a priority, I have found that it usually pays off for itself inside of a month. But note the key, the refactors that I focus on are ones that make day to day life simpler, and not ones that meet some arbitrary aesthetic of better or more general. Those refactors I’ve learned to be much more cautious with.
None of these things require advance planning. But they all make it easier to understand your existing code, and therefore make it easy to implement your next little chunk in a deliberate way.
8
It pretty much boils down to don’t guess. Mostly new programmers do it, but I’ve seen veterans do it too, because they think it saves research time. Something doesn’t work, so you add a +1 or a -1, change a true to a false or vice versa, reorder some statements, add or change delays, change thread priorities, and other small transformations, basically testing random permutations until it works.
That mostly applies to changing existing code, but also is a factor in brand new code, because no one truly starts from scratch. You’re always building on top of standard libraries, operating systems, or at least processor architectures.
In other words, you’re not done until you know why your fix works. The path you take to get there doesn’t matter so much. Even random permutations can sometimes be helpful to narrow down a bug that’s difficult to diagnose, as long as you take the time afterward to ask yourself, “Okay, changing true to false fixed it, but why?”
3
The most scary comment I ever encountered in a program was
Do not touch this. It works. We don’t know how or why, but it works.1
and it is scary just because it acknowledges that the piece of code was the result of programming by coincidence.
To avoid programming by coincidence, you should be able to explain (to a coworker, yourself or a rubber duck) exactly what the code does and why it works. The bullets for programming deliberately are mostly aid in moving towards that goal of being able to explain the code.
1For context, this comment appeared in the code that handles context switches in a primitive OS. The code had already been in production for several years when I encountered it.
6
For new programmers, the most important part of overcoming this is to really understand what they’re doing.
In many areas, when you don’t know how to do something, you just go by trial and error. Try something; if it works, great, if not, try something else.
In programming, especially when using a language that has the concept of undefined behavior (like C or C++), this approach simply doesn’t work, because success is no longer a boolean decision. You can have things that “kind of” work, that sometimes work, that work for some inputs but not others.
I have on occasion tutored new programmers, and the tendency to try typing random stuff to see if it works is common. They would type a line, and then turn to me and ask, “Would it work this way?” while it was clear that they had absolutely no clue whether it might.
The takeaway is that as a new programmer you really have to be able to explain what your code does. You have to learn to read code, not just write it.
(Of course that applies to seasoned programmers as well, but my experience here has been mostly with new complete beginners.)
1
It is far too easy to code, test and fix “on the racing line”. You have some functionality that given X & Y, produces Z. But what if X is corrupt and Y is unavailable? What if you’re unable to output Z? Constantly have in mind what can go wrong and make a note of it for the test cycle.
Keep your routines short and descriptive – the best code requires few (if any) comments.
Meaningful method, class and variable names go a long way to aiding readability.
If you come across a code smell then STOP. That smell is unlikely to go away and a little effort now could save you a huge amount of grief later on.
Include testing within your development process. I’d advocate the use of BDD rather than TDD as it forces you to describe what you’re aiming to achieve rather than blindly relying on a raft of tests which could give you a false sense of security.
Resist the urge to add extra cool features (unless it is your own pet project). Any extra code needs to be designed, written, tested and maintained. If it isn’t required by the client/business – you risk this becoming a huge drain on your resources.