>>> In article , prathapnirmal@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 would much rather see us clean up the header files and split out some of
the functional pieces of the code into separate .c files.

H

Harlan Stenn wrote:
>>>>In article , prathapnirmal@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.

>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 use
grep whatever *.c
or
grep whatever -r .
If that doesn't work in the directory I'm working in,
then I cd .. and try again. After doing that a few times
you learn your way around.

Occasionally, I have to look in /usr/include/

Sometimes the SCCS and BitKeeper files contribute a lot of clutter.

A literal "whatever" gets 141 hits in my copy of ntp-dev
and takes 1.23 seconds. The first try was slower.

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

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

Richard,

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.

Dave


Richard B. Gilbert wrote:
> Harlan Stenn wrote:
>
>>>>> In article
>>>>> ,
>>>>> prathapnirmal@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.
>

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

Richard B. Gilbert wrote:
> 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.

I always do that. It doesn't help to write code that noone else can
understand. There really is a need for design implementation documents
but in an open source project the documents get obsoleted very quickly.
Dave has plenty of project design documents on the implementation that
is heavily oriented towards how the algorithms work and why.

Danny

Thanks all for your responses and suggestions. I also suggest more
comments and documentation along the code rather than a separate doc.
I am not sure if there is a review process for new commits but it
will be great if we can stick to minimal set of documentation
guidelines. I am sure this will be atleast of minimal help to
developers and a lot of help to people who need to understand on
what's going on.

thanks
~

Pradhap Nirmal Natarajan
Pivot Systems
http://www.pivotsys.com
Trivandrum
prathapnirmal@gmail.com
prathap@pivotsys.com




On Nov 22, 2007, at 8:59 AM, David L. Mills wrote:

> Richard,
>
> 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.
>
> Dave
>
>
> Richard B. Gilbert wrote:
>> Harlan Stenn wrote:
>>
>>>>>> In article
>>>>>> ,
>>>>>> prathapnirmal@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.
>>
>
> _______________________________________________
> questions mailing list
> questions@lists.ntp.org
> https://lists.ntp.org/mailman/listinfo/questions

Danny Mayer wrote:
> Richard B. Gilbert wrote:
>
>>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.
>
>
> I always do that. It doesn't help to write code that noone else can
> understand. There really is a need for design implementation documents
> but in an open source project the documents get obsoleted very quickly.
> Dave has plenty of project design documents on the implementation that
> is heavily oriented towards how the algorithms work and why.

Dave's documentation is pretty difficult if, like me, you never studied
control systems, phase locked loops, frequency locked loops, etc. My
math goes only as far as elementary calculus and I have to strain to
follow that. . . . Math is a foreign language in which I never achieved
fluency!

Pradhap Nirmal Natarajan wrote:
> Thanks all for your responses and suggestions. I also suggest more
> comments and documentation along the code rather than a separate doc.
> I am not sure if there is a review process for new commits but it
> will be great if we can stick to minimal set of documentation
> guidelines. I am sure this will be atleast of minimal help to
> developers and a lot of help to people who need to understand on
> what's going on.
>

Look at https://support.ntp.org/bin/view/Dev/DevelopmentIssues for our
documentation guidelines.

Danny