develooper Front page | perl.perl6.internals | Postings from July 2002

Re: [PATCH] .dev files.

Thread Previous | Thread Next
Dave Mitchell
July 17, 2002 14:41
Re: [PATCH] .dev files.
Message ID:
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

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/ etc)


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.

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About