On Wed, Jul 17, 2002 at 01:42:17PM -0700, John Porter wrote: > > Andy Dougherty wrote: > > I think the purpose of the .dev files, as laid out in > > docs/pdds/pdd07_codinstd.pod, is a reasonable one. > > Here's an edited excerpt: . . . > > (Thanks, Andy.) > > Well, given that definition of the purpose, I must > persist in my opinion that the proper place for that > kind of doco is inside the source file. > > Some people may think it "strange" to find a discussion > of implementation issues in a source code file, but > I don't.
As the originator of the '.dev' file idea, my reasons for suggesting a separate file were: a) psychologically speaking, I supect that many people would feel uncomfortable inserting "mini-essays" in the middle of a source file, and there would thus be a natural tendency to pare them down and leave out stuff b) I didn't want the more general overview-type comments interspersed throughout the file, mixed in with detailed per-function comments c) not being in a src file would make it easier to cut+paste code snippets, examples etc without having to worry about nested /* */, or people confusing it with real code etc. One of the reasons I used numerical accuracy as an example was because in Perl 5, Nick's mini-essay on his stirling work *is* buried somewhere in the middle of the 10,000 line sv.c, and thus probably hasn't been seen by most people. If there was a .dev file, it would (hopefully) become a well-known starting point and thus things in it would more likely be drawn to the attention of the reader earlier. If the .dev file were to be merged into the src file, then I personally would want the entire contents to be inserted at the *start* (or maybe the end) of the file, rather than being intermingled. (Obviously per-function comments should remain next to the functions they comment). If the .dev file remained separate, then I would want it in the same directory as the corresponding .c file, to reduce the energy barrier of having to bother to deal with a second file. Especially if the .c files ever get spread round in a directory hierarchy (horrors like .../../dev/perl6/ops/foo.dev etc) Dave. -- This email is confidential, and now that you have read it you are legally obliged to shoot yourself. Or shoot a lawyer, if you prefer. If you have received this email in error, place it in its original wrapping and return for a full refund. By opening this email, you accept that Elvis lives.
