Unruh wrote: > "Richard B. Gilbert" <rgilber...@comcast.net> writes: > >> David Woolley wrote: >>> Joseph Gwinn wrote: >>>> We have moved from the meaning of status code 9514 to the more general >>> But you should have kept the thread, even if the subject changed. >>> >>>> issue of how NTP shall be supported, so I've collected the relevant >>>> threads below. >>>> More generally, it's hopeless to expect the world's sysadmins to read >>>> NTP code (or any other kind of code). They just don't have the time, >>> Generally, you only need to read a small bit of code to answer this sort >>> of question, but if you haven't got the time you should pay someone who >>> does have the time. > >> The ntpd distribution is about 70,000 lines of code! Expecting people >> to be able to find their way around is not realistic! Before the user >> can read that "small bit of code", he has to FIND it. He has to find it >> in 70,000 lines of code. Since the number "9514" may never appear >> anywhere in the code since it's a "bit mapped" value, what is the reader >> supposed to look for? > > Well, while that is true, grep can be your friend. Thus especially in an > output messages, grepping for that message will often send you to the right > place in that 70000 lines of code. > > >> Writing the documentation is part of producing the package. Programmers >> hate to write documentation but who else is going to do it? Who else can? > >> I once spent several days trying to understand the driver for the >> Motorola Oncore M12+T reference clock. I had to give up. I had no idea >> what the variables represented! I had 200 or so pages of Motorola's >> documentation for the hardware but that was not enough to help. > >> The programmers think it's obvious. It's not! I can see that the code > > No. The programmer thinks it is obvious on the day he writes it. Three > months later he has forgotten what in the world bTTlST was supposed to > mean. > >> swaps the positions of the two bytes in a sixteen bit word. If you >> don't include a comment explaining *why* you are swapping the bytes it >> makes the code extremely difficult to understand. It may be obvious to >> you that two bytes are being swapped to put them in "network order" but >> it certainly is not obvious to the reader. > >> If your code is difficult to read and understand, it is naturally going >> to be difficult to find people willing and able to help maintain it and >> to bring them up to speed! > >> A computer program is not just a series of instructions to be executed >> by the machine, it is also a document that must be understood by human >> beings! > > Agreed. > On the other hand the programmer is usually worried first about getting the > bloody code working, so spending a lot of time documenting something you > will probably change tomorrow seems pointless, and once the 5000 lines have > been written and debugged, it is far too late at night to document. >
Then God forbid that the code ever needs to be modified! The chances of introducing a bug are great. Most of the bugs will be found soon enough but there's always the one that occurs only on the night of the first full moon in a leap year! And lots of luck finding it!! _______________________________________________ questions mailing list questions@lists.ntp.org https://lists.ntp.org/mailman/listinfo/questions
