This is the mail archive of the mailing list for the GDB project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: What's an annex? stratum?

Paul Koning wrote:
"Robert" == Robert Dewar <> writes:

Robert> On Mon, Jun 25, 2007 at 03:19:32PM -0400, Paul Koning wrote: >> That's really unfortunate. Comments in code are useful but they >> are no substitute for properly written internals documentation.

 Robert> I disagree, properly arranged comments in the code can most
 Robert> certainly serve as internals documentation, and have a FAR
 Robert> better chance of being kept up to date. I am opposed to
 Robert> having separate internals documentation, I think it is much
 Robert> better to have this in the source files.

Usual practice is for source comments to be local explanation, not
global explanation.

Documentation provides context which is not often available in source comments. The source comments are valuable, but you have to know where to start or the context in which the comments are appropriate. (For example, my questions about annex and stratum are not answered in the source.)

Internals documentation provides a guide through the program in
some kind of logical order.  It's difficult to provide that order
at the file or function scope.

But in any case, if internals documentation existed in the sources,
I'd be a happy camper.

Me too.

Michael Eager
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]