Tracking Small Coding Decisions

A very wise man once told me "you can look at the code and see what but you can't look at the code and see why".

I strongly prefer to have the notes embedded as comments.

Unit tests record only what you decided to do, not what you chose not to do. They also don't record reasons for the decision. In fact, let's be strictly honest, all they capture is the specific implementation in code.

Is it not what you do with a unit-test, describe the capabilities of the code?

Good practice. Thanks. As to what are the better ways to do this... ugh, is that really a question?
I would follow up with the thought that the very low-level at which we find ourselves doing this (i do it repeatedly and voluminously inline with code...enterprise, vc, or home) is very much the "big design up front" ugliness at work. So we've been drawn to a "agile" perspective of the "minimal"; though many enterprise shops do not even require this much in the fight for time-to-market competitiveness. Obviously, ooops. Well imo there are many shades between BIG and small, and they are all rather unrelated to effectiveness and quality. Except that the developers and engineers that come after us already have, if you will, developed bias against some ways and are religious about others.
So the practice is best mentioned in passing perhaps; leave it not be seen as yet another idea from someone else, but an opportunity to get ahead of the pack. :-)

This is a great suggestion! Every now and then I look at my old code and wonder, why on earth have I done it this way? I even start re-coding, only to realize that other decisions have hidden undesirable consequences.

What is not clear is how to track the decisions in the most convenient and systematic way. Ideally, decision record should include a list of possible options, pro-s and contra-s for each, and the path taken. Perhaps it should also include an ID to make cross-references.

Where should the records be kept? Clearly, they should be tied with the source code and version control in some way. Keeping them in a separate Google document is not a good idea, because they will quickly go out of sync.

Perhaps, Doxygen comments is a good place for these records. I have not tried it myself, but a custom command can be created using \xrefitem to produce a separate Decisions section in the documentation.

Thank you for the article

Mikhail

Thank you for writing this article.

This sounds like a useful habit.