Ted Byers said the following on 12/18/2013 06:08 PM:
But don't forget, the case I mentioned occurred more than two dozen years ago, and often it was a defect in the original documentation, but even more often it was an error on our sysadmin's part, in not ensuring that the local copy of the docs was consistent with his optimizations. Only he had a hope of determining whether he messed up on his optimization or if he had neglected to update the documentation to reflect the optimizations he'd deployed.
To my mind this raises two questions. The first is 'what was he optimizing?' The kernel algorithms? Well that's a good place to optimise, especially if he an find a way to do so that is of benefit to all users. You say he was inclined to use assembler. Well many people can produce small amounts of code that are better optimized that compilers. That was especially true in the V7 days! It was doubly true as we were porting V7 and BSD2.8 to microprocessors back at the beginning of the 1980s and were using 'template compilers'. But these days compilers are 'expert systems' in code generation and you'd be hard pressed to better them over anything than a very small fragment. That being said, there are a lot of 'internals' whose documentation might get out of phase but really have little to do with what you coding. Could you be more specific please? Then there are things that while they might improve a lot of matters are a bit gratuitous. Perhaps the innards of strcpy could be done with machine specific single opcodes. Perhaps the trig functions could be coded as one assembler routine with different entry points. But that begs the question. How would these improvements get out of phase with the documentation? I can that, for example, the kernel user data structure went though a number of revisions between BSD2.4 and BSD2.8 in the beginning of the 1980s, as it did between V7 and SYSV (think: euid and family). But that only affected a a subset. Were you doing programming of things like 'ps'? The second matter is the sheer arrogance of the guy. Ah, but you go on to mention that!
But, to add to our "fun" he often told us that the system is fully documented in the code (and he meant the code, not comments embedded in it), and that we ought to just read the code: a rather arrogant response to us as many of his changes were done in assembly (he didn't trust the c compilers of the day to get the optimization right), and he was the only person in the department that knew assembly.
"Of the day"? Well 'that was then, this is now' and we're not him, so why the distrust of current MAN pages that have nothing to do with him? There is, I suspect there always has been, a class of programmers who take the attitude that the code is the documentation. These are the same people that never submitted 'design documents' or overviews. There are many apocryphal and true stories about such people. They are almost as bad as the people who write for i = 1 to 10 // i is the loop variable but never tell you why they chose one algorithm over another. Architecture documentation is every bit as important as code documentation. But NEVER confuse them with end-user or operational documentation. -- We all have two choices: We can make a living or we can design a life. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org