Problem:
We need to know how and why the design/architectural decisions were made.
What were the ramifications of different approaches?
Why was one approach chosen over another?
What future issues did we foresee squelching by this approach?
Context:
This information can't be derived from the current and previous versions of the code. Version control only tells us what we changed, not what we were thinking when we did it. Version control specifically does not tell us what we decided not to do.
Application:
This bit is broken, why don't we fix it this way?
Because we already tried that solution, and it had the following drawbacks... it is a Blind Alley
Because we thought it had the following drawbacks... it might be a Blind Alley
Gee, gosh, we never thought of that before. Let's invest time and money investigating that approach.
Without the Road Not Traveled history we may not know which of these three situations we're in. This is particularly evident in a project which has experienced any significant level of turnover. "Joe isn't with the project any more and he was the only guy who remembered anything about the XYZ component's history..."
Especially with user interfaces, when we try to make A easier to do, we end up making B more difficult to do. Later, when people complain about B being difficult to do, we fix that, but in a way that makes A difficult to do. Without the Road Not Traveled history, it's easy for successive releases to vacillate back and forth.
Solution:
Make a record of The Road Not Traveled. Did you do spike solutions and have them blow up in your face? Write it down. Did you have design bull sessions and mangle up some architecture that obviously wouldn't scale up or down? Record that. Did some little geek in the applications test department point out that your brilliant solution had one little, minor, teensy weensy flaw that would only cause a major meltdown under this particular set of conditions? Be sure to make a note of that, because somebody is guaranteed to replicate your genius somewhere down the road and he needs to know about the bear trap awaiting him.
Discussion:
Question: where do you store this record? As a separate "Road Not Traveled" document? But then how do you ever find relevant things in it? As a comment in the code? But then how do you find the actual CODE in amongst the cruft of old notes? There's gotta be a Best Practice for this one. -- Michael Chermside
That's an interesting question. The idea of there being a Best Practices solution for this is not real valid, though, in my experience. I have found that even a paper file of The Road Not Traveled is sufficient to store all the stuff that I deem worthy of remembering. If anybody else wants to come up with a better approach, I'm all ears. -- Marty Schrader
I think you must put it in the source code.
Imagine some future maintainer (perhaps yourself) is *editing* your source code, and you want to communicate to that person "I tried algorithm A but it didn't work because of Y", or "algorithm B would probably work better but this one seems adequate for now and there wasn't time to switch over and test it again", or "Whatever you do, don't use the -O3 switch, because then (with the 1.1a compiler) the compiler erroneously leaves out the interrupt routine". If you write this down anywhere other than as source code comments, you risk that documentation becoming detached from the source code and lost. -- David Cary
Hmm. The risk of some development notes like that getting "lost" is pretty slim if you have the simplest of housekeeping for files. Files may include things like sources (and documents) in VCS, paper in binders or hanging folders, spiral notepads in a desk drawer, or officious Laboratory Notebooks (with serial numbers and signed annotation) locked away in a fire-proof safe.
You are right that notebooks locked away in a safe are not "lost". But I still think they are less useful to the person editing the code than comments right there in the code. --David Cary
We can all agree that the notations affecting a particular implementation because of compiler concerns or whatever should be put in the source. However, those kinds of notes need to be somewhere else, too; if the tools or other conditions change and the source doesn't, then you'll never know you have some old kaka hanging on to your code because of ancient considerations. If you have notes that are read occasionally then you'll know to go back into the code and wipe out old workarounds and patches.
I would argue that anyone who would "wipe out old workarounds" is more likely to "read occasionally" comments embedded in the code than any other document. -- David Cary
But sometimes you have documentation that is generic to many projects. It violates Once And Only Once to copy the comment "Whatever you do, don't use the -O3 switch, because then (with the 1.1a compiler) the compiler erroneously leaves out the interrupt routine" into the source code of every project that uses the 1.1a compiler. -- David Cary, arguing with himself again.
Um, I make it a habit to re-read my old development notes (sometimes even to the point of going through my daily log) every few weeks or months when working on a project of any scale. I always have the lab notebook, daily log, and collection of weekly reports available to anybody who comes by my desk. Additionally, I'll create my own Three Ring Binder of stuff I have written in case anybody is interested in any docs I have created.
The reason one writes things down is not to bring about Carpal Tunnel Syndrome http://www.ctsplace.com www.ctsplace.com, it is to convey knowledge in the least painful method. Despite everything that the XPers on this Wiki say about how talking is the way to convey such knowledge, writing it down is still the best way. If I can't use my own documents then certainly nobody else can use them, either.
If the version of the code that you are discarding has been committed to your source control system, then putting the explanation into the change log for the file should be sufficient documentation. This approach will not, however account for versions discarded before ever reaching the source control system. You would need to either introduce a culture of checking in broken code (which is probably a bad idea) or fall back on one of the other tracking methods discussed here.
Nah, it isn't sufficient for a bunch of the reasons outlined above. Unless you want to make change log entries read like novellas you need to have a separate set of notes that captures your thinking and decisions. The code in VCS is simply there as a footnote to history, showing what the approach might have looked like but didn't take final form because it was Non-Functional Gear.
Let's try to keep in mind that notes about the code need to be kept with the code (and some other places, too). Notes about development need to be kept with other notes. Use good sense in putting like things together. Eh?
I personally re-wrote a function (the same one!) 3 times. Not including the first time I wrote it. Each time I looked at it, saw that it was doing something stupid, and started re-writing it to be less stupid. I'd get halfway done when I realized that the non-stupid way doesn't work. The second time, I also remembered that I'd done this before and slapped myself. The third time, I slapped myself twice and stuck in a comment about why it's done the (apparently) stupid way and why the (apparently) smart way doesn't work.
Andy Dent describes a practice which he calls "Diary Driven Development" which includes the maintenance of a design decisions document (See www.ddj.com 
). Recording design decisions, alternatives and reasoning can be done easily with a blog or similar journaling tool- which allows links to these references to be embedded easily in comments near the relevant portions of code (and also allows for searching e.g., a specific developers blog for any entries _near_ the time that he made a certain change.) This practice has proven helpful in digging up histories on bugs and reasons why the code is the way it is many times in our shop.
See original on c2.com