Re: comments as preserved meta-data (was Re: Embedded comments ...)
Timothy, you raise a good point that I had been thinking about earlier as a
consequence of my proposal about comments being preserved and attached as
meta-data to what is most appropriate contextually.
I'm thinking that it should be formally defined somewhere (maybe as an extra
section in the synopsis about POD, or maybe not as parsing POD is supposed to be
agnostic to Perl versus other languages AFAIK) as to where exactly one should
put comments or how they should be formatted such that they would be
unambiguously attached to something specific.
In my mind, any of the following could have a comment meta-data associated with
it specifically:
- A single statement in a routine.
- A single sub-expression within a statement.
- A contiguous sequence of statements.
- A single code block (which is brace-bounded).
- A single parameter or other trait of a routine.
- A single routine.
- A single class/role/etc attribute declaration.
- A single statement outside a routine (misc things inside package decl), or a
contiguous sequence of said.
- A single package.
Now in my experience, a comment for something either appears just before that
thing, or just after that thing, or in the case of a brace/bracket/etc-delimited
thing, just inside the opening brace/bracket/etc of the thing. Or thanks to
Perl's unspace or embedded comment (name?) feature, otherwise in the middle of
the thing it describes.
Generally speaking we want to support whatever commenting styles people are
already accustomed to doing, and the formal definition of what to attach a
comment to should work with all the common cases where possible, and have a
reasonable fallback in the case of ambiguity.
For some examples, of varying ambiguity:
@lines = slurp(file); # attach to single stmt this follows
# also attach to single stmt this follows, due to indent
@foo = # attach to single stmt which is assign stmt
map { ... } # attach to 'map' sub-expr
grep { ... } # attach to 'grep' sub-expr
map { ... } # attach to 'map' sub-expr
;
# attach to routine 'foo', same indent level
sub foo () {
# also attach to routine 'foo'
}
# attach to the contiguous seq of stmts until next same
# kind of comment
@lines = slurp(file);
@otherlines = map { s/foo/bar/ } @lines
putfile(file, @lines);
# attach to whole if-elsif-else block etc
if 1 {
# attach to the innermost code block this is inside
# which is the 'if' option block
...
}
else {
# attach to the 'else' option block
...
}
Well there is still much to think about, and I could probably develop proposal
details further, but some things could be made more explicit, eg, the comment
just inside the opening 'if' block could be further tersely annotated, say with
a differing punctuation char immediately following the #, to distinguish say
whether it was for the 'if' block it was inside or for the set of statements it
immediately precedes within said block.
I think this can be made to work without much fuss, and it will be valuable.
Both for introspection of op-tree as well as the ability to regenerate the
original or as-if-original Perl code from the op-tree with more pleasing results.
-- Darren Duncan
Timothy S. Nelson wrote:
I had an interesting idea I wanted to put out there. If I'm being a
good boy and commenting my code, I do things like the following pseudocode:
# Get the stuff and do other stuff with it
@lines = slurp(file);
@otherlines = map { s/foo/bar/ } @lines
putfile(file, @lines);
$t = 3;
Anyway, my point is, how much of the code does the comment apply to.
I was thinking it might be a good idea to have a comment that indicates
when the code that the previous comment applies to ends. So you could
have something like this:
#{ Get the stuff and do other stuff with it
@lines = slurp(file);
@otherlines = map { s/foo/bar/ } @lines
putfile(file, @lines);
#}
$t = 3;
...and then both people and parsers would be able to determine which
part of the code your comment applies to, and we'd be able to
automatically determine the comment coverage of our code, as well as the
test coverage. I'm perfectly well aware that the syntax I suggested
about conflicts with the existing Perl 6 spec, and I'd love it if people
suggested a better alternative.
Just to make myself clear, in the above example, I'm not commenting
out any of the code, merely indicating which code the comment applies to.
Anyway, just some thoughts...
Re: comments as preserved meta-data (was Re: Embedded comments ...)
On Thu, Aug 13, 2009 at 1:00 AM, Darren Duncandar...@darrenduncan.net wrote: Timothy, you raise a good point... [discussion] I think this can be made to work without much fuss I'm curious about these sorts of conversations, and the way the community works in relation to them. I'm also curious about this specific conversation, and the ability (or otherwise) to get a facsimile of what we want by using existing P6 specc'd features, especially morphing the grammar, and macros. First, about this conversation and the way the community works... We just had a bunch of threads touching on this stuff. Larry++ then made a change to the spec. Notably, @/Larry didn't post within the discussions I read and made the spec change while discussions were still going strong, with ingenious, fresh, thinking. (That suggests to me that he/they were trying to shut down debate, presumably due to viewing it as bike shedding, at a time when such could be considered ever more dangerous, perception- and productivity- wise. Leadership in an anarchist context is a tough role!) Despite @/Larry's move, you have continued, and I appreciate that, and hope @Larry are still paying some attention. Second, I'm hoping that @Larry are confident we'll get more or less what we want in the end, due to POD power and/or grammar morphing and/or macros and/or some other features we haven't thought about. I'm hoping that, rather than that what's happening is that @Larry are running out of time and patience (although that would be quite understandable!). There have been many of these comments discussions over the years. In particular, a notable multi year long exchange, best represented by Mark Overmeer and Damian Conway, about how best to weave documentation and code. Indeed, this issue goes way back and way deep; I recall Ward Cunningham's promotion of 'literate programming' in the mid 90s, in which, iirc, he talked of Donald Knuth's promotion in the 70s of the idea of code and comments being woven extremely closely together such that neither is dominant, and one can actually turn things inside out and have code embedded in commentary rather than the other way around. A radical paradigm indeed! Anyhoo, I'd love to see a session of brainstorming, with nitty gritty detail, about possible ways to get what you guys and Mark and I and perhaps others think we would like to see in the way of super tightly woven together comments and code, where said brainstorming initially works within the creative constraint of leveraging the P6 spec as is, plus reasonable extrapolation of unspecced bits. Think grammar morphing, aspects of macros, the existing unfinished POD6 spec, and any other relevant existing bits I'm forgetting. Did that make sense? Anyone interested? ;) -- love, raiph
Re: comments as preserved meta-data (was Re: Embedded comments ...)
Raiph Mellor raiph.mel...@gmail.com wrote: Anyhoo, I'd love to see a session of brainstorming, with nitty gritty detail, about possible ways to get what you guys and Mark and I and perhaps others think we would like to see in the way of super tightly woven together comments and code, where said brainstorming initially works within the creative constraint of leveraging the P6 spec as is, plus reasonable extrapolation of unspecced bits. Think grammar morphing, aspects of macros, the existing unfinished POD6 spec, and any other relevant existing bits I'm forgetting. Excellent idea. But may I suggest you perhaps might like to hold off that discussion until next week? @Larry had some very fruitful discussions about the long-overdue Pod spec during YAPC::EU last week and, as a result, I plan to (finally!!!) release a new version of S26 this week-end. I very much hope that this new revision will satisfy The Overmeer Desiderata [1] too. Damian [1] Sounds like a Robert Ludlum novel, eh?
Re: comments as preserved meta-data (was Re: Embedded comments ...)
Excellent idea. But may I suggest you perhaps might like to hold off that discussion until next week? @Larry had some very fruitful discussions about the long-overdue Pod spec during YAPC::EU last week and, as a result, I plan to (finally!!!) release a new version of S26 this week-end. I very much hope that this new revision will satisfy The Overmeer Desiderata [1] too. Damian [1] Sounds like a Robert Ludlum novel, eh? With this whiny man exchange ultimately having bourne supreme fruit, the apocalypse watch for the post damian weekend begins... -- love, raiph
Re: comments as preserved meta-data (was Re: Embedded comments ...)
Raiph Mellor raiph.mel...@gmail.com hyperpunned: With this whiny man exchange ultimately having bourne supreme fruit, the apocalypse watch for the post damian weekend begins... ARRRG! Damian ;-)
Re: comments as preserved meta-data (was Re: Embedded comments ...)
I had an interesting idea I wanted to put out there. If I'm being a
good boy and commenting my code, I do things like the following pseudocode:
# Get the stuff and do other stuff with it
@lines = slurp(file);
@otherlines = map { s/foo/bar/ } @lines
putfile(file, @lines);
$t = 3;
Anyway, my point is, how much of the code does the comment apply to.
I was thinking it might be a good idea to have a comment that indicates when
the code that the previous comment applies to ends. So you could have
something like this:
#{ Get the stuff and do other stuff with it
@lines = slurp(file);
@otherlines = map { s/foo/bar/ } @lines
putfile(file, @lines);
#}
$t = 3;
...and then both people and parsers would be able to determine which
part of the code your comment applies to, and we'd be able to automatically
determine the comment coverage of our code, as well as the test coverage. I'm
perfectly well aware that the syntax I suggested about conflicts with the
existing Perl 6 spec, and I'd love it if people suggested a better
alternative.
Just to make myself clear, in the above example, I'm not commenting
out any of the code, merely indicating which code the comment applies to.
Anyway, just some thoughts...
:).
-
| Name: Tim Nelson | Because the Creator is,|
| E-mail: wayl...@wayland.id.au| I am |
-
BEGIN GEEK CODE BLOCK
Version 3.12
GCS d+++ s+: a- C++$ U+++$ P+++$ L+++ E- W+ N+ w--- V-
PE(+) Y+++ PGP-+++ R(+) !tv b++ DI D G+ e++ h! y-
-END GEEK CODE BLOCK-
