...The way I found it.

When I first learnt Java, it seemed like a huge step forward. This last fortnight, I’ve been making that discovery all over again – I’m working on a C++ system for the first time in six years.

Case in point: just this morning, a co-worker and I figured out a trick that will save an error-prone, cut-and-paste duplication of thirty or forty struct definitions. The saving comes at a small cost: there will be strange #ifdefs dotted around the header files.

We were discussing whether or not to document the #ifdef trick for the developers who come after us. My co-worker took the position¹ that no documentation was needed. His argument went along these lines:

You know what’s going to happen… [the developers who come after us] are going to say “Well I tried taking it [the #ifdefs] out, but it didn’t work, so I put it back the way I found it.”

Since the #ifdefs will always be put back the way they were found, they will always keep working. Understanding of the mechanism the #ifdefs (ab)use, or even the intent of the #ifdefs, is not necessary. And, as the sole purpose of the proposed documentation would be to promote understanding, the proposed documentation is not necessary. Q.E.D.

¹ With his tongue in his cheek, of course.