On 13-12-18 06:36 PM, Anton Aylward wrote:
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'.
I was never masochistic enough to ask what he was doing, after the first time. You see, he'd get excited and start talking tech as if he were talking to himself. Once that happened, what he said was as about intelligible to us as swahili is to most Americans. None of us could make sense of him once he got started. We'd just nod approvingly, especially as he showed us the benchmarks he'd produced showing the benefits (which he needed to get departmental approval for his budget). Back then, I knew number crunching specialists that would resort to assembly, so I knew that if speed were critical, it could be improved by resorting to assembler.
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? Like I said, most of us gave up on trying to understand the details of what he was doing. I really didn't care as long as my programs produced
Right, but I was talking about decades ago. provably correct answers (I was, and am, primarily a number cruncher, and spent my time developing either modelling or statistical programs).
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'?
All the programs I wrote involved some aspect of number crunching. For example, I'd generate test data, for which I knew precisely the distribution moments, and correlations among variables, and write code to do the statistical analyses. The test data was used to verify that the programs were correct, and that they could then be used on data for which we did not know the relationships or correlations. At the time, also, I developed computer based teaching materials, to run on DOS (so I did my share of bit twiddling on video RAM), and I, and the department, bought the first generation PC's. I developed these programs on mine, and delivered them to the department to deploy on their's. Once I had mine, I never had to deal with his optimizations again. ;-) I'd just do my computing on my PC, and deliver the result to my supervisor on a 5 inch floppy.
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?
I did say it was decades ago. But, that was also the last time I had to routinely use a unix machine, until I recently started to refamiliarize myself with unix by studying Suse and Ubuntu Linux. I have not yet had sufficient good experiences with man pages to outweigh the unpleasant memories of the bad experiences of decades ago.
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.
agreed. And I have had experience with companies that explicitly forbade us from writing documentation. One president of a consulting company told me it was a waste of time to write documentation. Of course, I wrote documentation anyway, in the form of comments in the code focussed on detailing what the algorithm is and why it was used. Many of the applications I developed are quite complex and it would be a challenge for even a senior engineer to figure out what was done and why (I am sure he'd could do it, but at the cost of spending more time to do so than it would take to redevelop it de novo): part of this is that the mathematics involved is well beyond what an undergraduate student would normally encounter.
Architecture documentation is every bit as important as code documentation. But NEVER confuse them with end-user or operational documentation.
You're absolutely right there. While programmers generally don't like writing documentation, I write it (even though I hate it - it takes longer to get right than it takes to write the code) and I require the programmers I work with to do so too (though I don't let them touch the user documentation as they haven't learned, yet, that users speak a different language than software engineers and programmers). I write my user documentation in cooperation with the support guys (and they're not programmers, but rather guys that spend almost all their time talking with customers and end users; and teaching the latter). Cheers Ted -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org