In a preachy mood: Today I spent some time talking to someone about how a piece of code that is going to affect his hapiness (aka he is responsible for) has some really bad design decisions in it. We went over how there is this little bug that shows as a consequence of this design flaw. The bug itself has an easy fix and such, but the underlying reason is that several layers of leaky abstractions interact with each other in unhappy ways.
In short I was trying to tell him that its not a bug, but that its bad design waiting for a victim - this should be better described as a pit or a trap than a bug. Bugs are visible warts, pits are lurking demons. Bugs are plain as day, easy to justify - pits are lurkers, those who can tell good code from bad, feel uneasy in their precense.
Do you have pits in your code? Do you have a sense of what parts of your code are pits? If you had to choose between fixing a pit and a bug, what would you do?
I believe everyone's code has pits to varying degrees and that they are completely unavoidable beacuse there is simply no such thing as a perfect apriori design. That said, here are some slightly more interesting questions:
If you had to implement something new - there is solution 1 that is going to introduce a pit but will deliver said target surely and quickly and there is approach 2 that will potentially eliminate the pit, but is going to be far more expensive to implement - How would you choose which approach to take?
I usually go ahead and implement the pit when I dont have enough information to decide between the two. Often there are pits that will never surface and no one gets trapped in them. When I dont know enough implementing the pit is a good way to (1) get my work done (2) ensure that I am collecting data so that the next time I know what the real costs are.
Its vastly more valuable to document the fact that a choice was made based on the lack of sufficient information, than the excrutiating details of choice itself. Pits turn into chronic illnesses of your code base when no one knows why ceratin decisions were made, and hence no one ever feels comfortable back tracking over a bad decision. Once I know an ill-informed choice was made, and once I know the price I am paying for it, its a lot easier to back track over it.
In other words, dont just document your design, document your choices in the context of your design space - it will keep you honest. Well written code to a large extent is its own documentation - what it is not a good documentation of is the choices that you did not take and the reasons why you did not take them.
Thoughts?