[ntp:questions] Details about code structure

Hal Murray hal-usenet at ip-64-139-1-69.sjc.megapath.net
Thu Nov 22 02:52:21 UTC 2007


>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.

-- 
These are my opinions, not necessarily my employer's.  I hate spam.




More information about the questions mailing list