( from MethodCommenting: )

'''Blind Alley.'''
There's often a solution that's "simple, obvious, and '''wrong'''."
Usually, it's in version 1.0 of the code,
and replaced by something less simple, less obvious, and less wrong in version 1.1.
Someone who comes back to the code alter is often tempted to unknowingly repeat the mistakes of the past.
''Therefore:''
When you replace obvious but incorrect code with non-obvious but correct code, '''comment''' the old approach as a blind alley that shouldn't be traversed again.
----
Many times one takes a path that seems reasonable, but each improvement gets more and more difficult. Later you discover a different path that looks like it would get better results with less programming effort. (For example, premature optimization -- see WellFactoredCodeLeadsToBetterOptimizations).

Then you have a choice: would it take less effort to
* slog a little further until it is GoodEnough (but leave a comment about the promising new path), or
* abandon this path, and RewriteCodeFromScratch (and leave a comment about why the old way was inferior).

Other times it becomes clear that this path won't work ''at all''. In those cases you're forced to abandon this path, and RewriteCodeFromScratch.
----
See: TheRoadNotTraveled, HistoryMatters, PrepareTheWay, PleaseReinventTheWheel

CategoryDocumentation