Details about code structure - NTP

This is a discussion on Details about code structure - NTP ; Hi All, Which will be the best document to refer if I need to know information about the organization of code in ntp? I am looking for information like, * a convenience library is created in libopts directory which is ...

+ Reply to Thread
Results 1 to 11 of 11

Thread: Details about code structure

  1. Details about code structure

    Hi All,
    Which will be the best document to refer if I need to know information
    about the organization of code in ntp? I am looking for information like,
    * a convenience library is created in libopts directory which is further
    used to link against the final exe
    * a library is created in libntpd to be linked against ntpd
    * ntpd uses libs made in libopts + libntpd

    and so on. One obvious way is to look at the makefile.am in each directory
    to figure out what is made out of what? But I thought I will put it across
    to everyone to see if there is any documentation related to this. Also is
    there a design doc that talks about this or other details?

    --
    Prathap
    mobile: +91 99465 56643
    Pivot Systems
    http://www.pivotsys.com

  2. Re: Details about code structure

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

  3. Re: Details about code structure

    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.


  4. Re: Details about code structure

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


  5. Re: Details about code structure

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


  6. Re: Details about code structure

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


  7. Re: Details about code structure

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


  8. Re: Details about code structure

    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

  9. Re: Details about code structure

    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


  10. Re: Details about code structure

    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!






  11. Re: Details about code structure

    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

+ Reply to Thread