[ntp:questions] Details about code structure

Richard B. Gilbert rgilbert88 at comcast.net
Sat Nov 24 19:46:28 UTC 2007


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!








More information about the questions mailing list