You must read the code.
(HT: Dr. Masaaki Mizuno)
I took a class long ago called Advanced Operating Systems taught by one of my very favorite professors, Dr. Mizuno. I think it was numbered at 720. In that course, we had a textbook which mostly contained several thousand lines of C and assembly language source that made up the operating system known as Minix by Andrew Tanenbaum (also author of the book). (For those who don’t know your OS history, Linux was sort of a fork/reaction to Minix and the heated correspondance between Andrew Tanenbaum and Linus Torvalds are the stuff of Computer Science legend.)
Anyway, in that book Tanenbaum had several comments about what the code was doing. Several of those comments were misleading or flat out wrong. In fact, one of the most critical pieces of code only contains misleading/wrong comments. This wasn’t intentional, but sometimes when software changes or when the author of the software has a different mental map for what’s going on, one that might be useful but is ultimately flawed. In any case, Dr. Mizuno often repeated the mantra “You must read the code” in his thick accent and it has stuck with me ever since.
I do not trust any code I cannot read. I generally read the documentation of a piece of software and then immediately start reading the source code from there because so much documentation is out of date, misleading, or simply wrong. The only accurate specification describing what a piece of software does is the code itself.
Copyright © 2016 Sterling Hanenkamp.