[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