[ntp:questions] Details about code structure
David L. Mills
mills at udel.edu
Thu Nov 22 03:31:15 UTC 2007
Hal,
There is a page in the documentation on how to write a reference driver.
It's old, but mostly correct.
Dave
Hal Murray wrote:
>>I had my computer count the lines of code in one of the older versions,
>>about two years ago. 70,000 or so lines of code may be a small number
>>to you but it seems like a lot to me. I once looked at the code for the
>>Motorola Oncore driver to try to understand what was going on and failed.
>
>
> It hasn't changed much. About half of it is the refclock drivers.
>
> I haven't looked at the Oncore driver. You can often learn things
> by looking at the code in other drivers.
>
>
>>It's never easy to wrap your mind around someone else's code, especially
>>when there's that much of it. It's even tougher if you're not really
>>fluent in C. I can struggle though it but I'm not what you'd call fluent.
>
>
> It's even tougher when the basic algorithms are complicated
> and full of heuristics that you may not understand.
>
>
>>Rather than writing a separate document, I'd recommend carefully
>>commenting the code itself. This would include identifying what the
>>variables and data structures represent, and cross referencing the code
>>to the RFC. I'm not going to hold my breath though. Most programmers
>>would rather write code than documentation.
>
>
> In my opinion, the ntpd code is actually quite well commented.
>
> Yes, the .h files could use some more hints.
>
> Just picking sensible variable/procedure names is half the work.
> (This isn't (old?) FORTRAN with a 6 character limit.)
>
> There is an interesting tradeoff. If you don't know anything,
> you would like a lot of comments that tell you all the details
> that you don't know yet. If you are a familiar with a chunk of
> code, all those comments are clutter. What you really want
> are descriptions of the big picture and details that aren't "obvious"
> from looking at the code.
>
>
> I was at a talk the other day. The context was computer literacy
> in the sense of normal people being able to read code. (A few
> thousand years ago, normal merchants paid scribes to read/write
> for them.) One interesting discussion was about how to say
> "don't do X" or "use hash tables rather than linked lists because ..."
> in formal code as compared to a textual comment that may be in
> a language the reader doesn't understand.
>
More information about the questions
mailing list