24

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.

EDIT:

a summary from your posts:

  • Don't guess your next move, prove it is correct
  • Unit test and refactor much as possible, when necessary
  • Add features–compile–test often
  • If you can't explain the code to a noob, you're probably programming by coincidence.

BTW, it is hard to accept an answer, it is really hard. All answers are really great :)

| improve this question | |
  • 6
    It would help people who might not have read the book for a long time to have a link like pragprog.com/the-pragmatic-programmer/extracts/coincidence. – btilly Jun 19 '13 at 7:15
  • Unless you have a very short programming career (or are a one man shop), you're likely to come across code that looks oddly familiar and some code-walking later, the penny drops: it is yours. It isn't only an Open Source consideration... – Robbie Dee Jun 19 '13 at 16:36
  • @Robbie Dee. can you clarify it a little more? I dont get you. Indeed, I have a short programming career and thats the reason of the junior-programmer tag. – py_script Jun 19 '13 at 20:34
  • 2
    @py_script I was just making the point that you can just as easily come across your own code years later (and be flummoxed by it) as someone else's. So if you start off with good habits, this will pay dividends later. – Robbie Dee Jun 19 '13 at 20:53
26

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.

| improve this answer | |
  • Thanks, really good answer. I think the part about the cycle is really valuable. Can you give me examples of refactoring that you should do them, but will take really long to implement and that may discourage someone? – py_script Jun 19 '13 at 20:39
  • 1
    I have lots of examples. In a C++ project I created classes without stringification methods. Once I created those, debugging became easier and development sped up. In a Perl project we had a configuration hash where each developer had their own tweaked copy of each new configuration. Adding configuration parameters was a pain because you had to edit every developer's config. I wrote template system for hashes, and that became easier. In a reporting system I added a feature to show intermediate results. My development sped up, and I even got a user bug report... – btilly Jun 20 '13 at 23:56
  • 1
    where the finance department had traced my logic, and found the exact query on which I went wrong and what my bug was. (I was accidentally squashing duplicate rows with UNION where I needed UNION ALL.) And so on. – btilly Jun 20 '13 at 23:59
  • 1
    Inside of a month? I usually find that each time I touch code I feel should be refactored, but haven't refactored, it takes nearly as much time as it would to refactor it. – Amy Blankenship Jun 21 '13 at 2:51
  • 1
    @AmyBlankenship Yes. Inside of a month. Sometimes ridiculously inside, sometimes not. The config file thing I mentioned above is an example of "sometimes not". It took a few days for me to write, document and test a new template engine. Then rewrite the existing config to use it, and be much shorter, but produce the same exact data structure. (That was the hardest part of the project.) So..days wasted, with absolutely no visible result. Yet the effort paid off in just under a month, but has been earning interest ever since. – btilly Jun 21 '13 at 5:00
42

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?"

| improve this answer | |
  • 1
    Excellent point +1. Nowhere does this apply more than code fixes... – Robbie Dee Jun 19 '13 at 15:59
  • True for me too, unfortunately. To be honest there are objective difficulties like lack of documentation sometimes. Today, I was fixing my code a little, and I came up to the fact that I didnt know what a parameter is useful to, because there was lack of documentation. We just know it is a number. – py_script Jun 19 '13 at 20:47
  • I admit. When facing leaning toothpick syndrome, it can be easier to stack the \s until it works than it is to figure out how many layers of escaping you're contending with... – btilly Jun 21 '13 at 0:01
16

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.

| improve this answer | |
  • 2
    this is also called voodoo chicken coding c2.com/cgi/wiki?VoodooChickenCoding – minusSeven Jun 19 '13 at 7:38
  • 1
    Even if the coder believes it to be true, that sort of comment is massively unhelpful. The code may well have been complex, but if you were to otherwise read the code, you might think it was straight-forward. All the comment does is increase paranoia! – Robbie Dee Jun 19 '13 at 8:07
  • 3
    This can also happen when maintaining an old codebase, in a language most of the current development team isn't very comfortable with. – pcurry Jun 19 '13 at 12:50
  • So rubber duck is not only for debugging. Nice...I think we are working on the same company, we have many comments like this :P – py_script Jun 19 '13 at 20:42
  • there are situations when a fix just works due to a glitch in an API, and there is no better and logical fix. Debugging some compiled third party lib can go as deep as kernel debugging. And even if you found the problem, after hours of debugging there is little you can do. So you approach the problem differently. You adopt the "black box" model which enforces you to program by coincidence. You play around with the weird behavior of the black box and if you manage to get it to work the way you want, GREAT, add a comment with "magic do not touch" and move on. – Radu Simionescu Mar 24 '15 at 23:33
7

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.)

| improve this answer | |
  • <<You have to learn to read code, not just write it.>> So, about my initial question, do you think it will help me to add features on open source projects? – py_script Jun 19 '13 at 20:49
2

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.

| improve this answer | |

Not the answer you're looking for? Browse other questions tagged or ask your own question.