On Mon, 2005-02-14 at 14:38 -0600, Andy Lester wrote:
> Anything that starts with # is ignored by the harness. That's very
> different from the test comment.
Yet Test::Harness::TAP calls them comments and comment lines!
Put on my boots for a second. Here's what I'm trying to explain:
T::H ignores everything on the test line that doesn't look like a Perl
comment and pays attention to everything that does. The first part of
the test line (before Perl's comment character, the octothorpe) is the
test comment. It is optional. The rest of the line is also optional.
If present, it must follow the '#' character. T::H will process this
and may change how it thinks about the test based on its contents.
You can also add additional information to the test. T::H will
silently ignore all comments. These must come on their own lines and
start with the '#' character.
We have three separate things:
1) an optional description of a test, which occurs after the test number
but precedes an optional '#' character and anything following until the
newline character, having no effect on parsing
2) a directive, which starts somewhere after the test number with the
'#' character, continues to the end of the line, and changes how T::H
interprets the test's status
3) additional diagnostics for a test, which by convention go out on
STDERR, do not appear on the same line as the test number or items #1 or
#2, and have no effect on parsing, existing only for human convenience
#2 and #3 look similar but act differently. Unfixable by about 16
years. Fine.
#1 and #3 act similarly. Great! They should.
However, throw the word "comment" in a room full of Perl programmers and
see how many of them want to play tic-tac-toe. I dare you. Calling two
things that look differently but act similarly by the same name may
work, but that name means something significant that has more to do with
the two things that look similarly but act differently! I think that's
a significant conceptual problem for people who haven't yet absorbed the
intrinsic knowledge of each part.
Here's my list of suggestions for each:
1) label, description
2) directive, instruction
3) diagnostic
I want to avoid the word "comment" altogether, making the optionalness
of #1 and #3 evident in their words, the activeness of #2 evident in its
word, and any comparison to Perl's comments in syntax or name go away.
-- c
