[ntp:questions] Details about code structure

David L. Mills mills at udel.edu
Thu Nov 22 03:29:03 UTC 2007


May I recommend the skeleton appendix in the RFC draft along with the 
main text and flow diagrams. More detailed diagrams are in the UDel 
report cited in the RFC. I took great care in commenting the protocol 
and crypto source code, expecially since some of my code is fifteen 
years old and I might not remember why I did what I did.

There would be considerable value in a utility that could parse the 
makefiles, identify the build sources and header files, then make an 
index showing where each external variable is referenced. I did that 
manually for the code skeletoon, but that's not the real article.


Richard B. Gilbert wrote:
> Harlan Stenn wrote:
>>>>> In article 
>>>>> <c9950d540711171143r4208d50q4eb8ec44f5fd594 at mail.gmail.com>, 
>>>>> prathapnirmal at gmail.com (Prathapnirmal) writes:
>> prathapnirmal> Hi All, Which will be the best document to refer if I 
>> need to
>> prathapnirmal> know information about the organization of code in ntp?
>> And the answer is...
>> prathapnirmal> One obvious way is to look at the makefile.am in
>> prathapnirmal> each directory to figure out what is made out of what.
>> That is the definitive answer.
>> prathapnirmal> ... I will put it across to everyone to see if there is
>> prathapnirmal> any documentation related to this. Also is there a 
>> design doc
>> prathapnirmal> that talks about this or other details?
>> There really isn't anything else.
>> The "market" for such a document seems to be small, and then there is the
>> issue of who would maintain it. Now, if somebody were to volunteer to 
>> write
>> and maintain such a document I'd be happy to put it in the distribution.
>> Would such a document really be all that useful?  It seems to me that the
>> codebase is pretty small, and it should not be all that hard to figure 
>> out.
> 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'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.
> 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.

More information about the questions mailing list