Document Your Christ-Damned Code

In the context of my research, I've been running a large number of test cases on triangles, which happen to be a good way to look at crystals. My tests were generated with the use of (among other things) a function that takes a triangle and splits it up into four other triangles, like so:



These four sub-trianges are then stored in an array.

Figure 1 above shows the ordering of the sub-triangles, according to the comment above the function I used. Figure 2 shows the actual ordering of the sub-triangles in the array:



Note the subtle but important discrepancy. My test cases were meant to test adjacent triangles, so I used triangle 3 and a randomly-generated second triangle - but by the actual ordering of these triangles, triangle 3 probably wasn't adjacent to the other one.

These worthless tests ran for about 24 hours before I figured out the problem. Now, the fact that I didn't catch this before wasting several trillion processor cycles and ~76 kWh of energy is my own fault, but all this could have been averted had the function been properly fucking documented in the first place.

Note that I'm not saying "comment your code". The code was commented - but the comments themselves contained negative information. The whole point of comments is to prevent the reader from having to go through, line by line, and discern for themselves the functionality of the program - but if you can't trust the comments to be accurate, you have to do that anyway.

So, document your Christ-damned code. The kilowatt-hours and processor cycles you save might be your own.

--
wake up, put on my riot gear