I propose that the compositional grammar support comments in the same way as the ECL. Not just for completeness and symmetry with the other languages: I actually tried to comment out a portion of an expression before quickly realizing it made the expression illegal!
12 Comments
Daniel Karlsson
I have Java comments in my parser, // and /* */. Very handy.
Peris Brodsky
Assuming this is a reasonable proposal, I've already added C-style comment support to my SCG parser.
Java-style line comments would be just as useful, so I will follow your example for SCG, and also apply this for my ECL parser.
Michael Lawley
/* comments good but // will behave badly when people strip out new lines (very common for expressions and APIs)
Daniel Karlsson
Why would this matter when parsing SCG?
Also checked the Java specification, and the end-of-line comment does not include the EOL char(s).
Peris Brodsky
Michael, do you mean that people will necessarily strip newlines from an expression to pass it as an API parameter?
Ed Cheetham
No doubt I'll be wrong, but here goes...
The developer/experimenter use case that 'comments in an expression' support is compelling, but I'd be concerned that writing it into the specification comes with new risk. In particular, the theoretical availability of any number of 'comment' fields in the context of the 'Expressions In Health Records' use case could easily be overloaded by local communicating parties for well-intentioned but ultimately problematic purposes.
If it is possible to mitigate against this risk then I'm not opposed.
BTW - Linda, I note that the slash+star notation explaining comments has become corrupted in a few places in the ECL document (confluence & pdf). In two places - 5.3 (comment explanation) & 6.6 - I suspect this is because confluence has interpreted the stars as bounding a 'bold' section, and in 5.3 'comment = "/" *(nonStarChar / starWithNonLSlash) "/" the stars have disappeared completely.
Ed
Daniel Karlsson
Good point. I think this problem can be mitigated by e.g. stating clearly that comments may not be persisted or kept when transforming or otherwise using the expressions. I'm using comments extensively in SCG source files during development for protect specific metadata, knowing that this will not be kept (in comment form) when/if content is moved into SNOMED CT. Using SCG in this way may not be for everyone but works for me.
Linda Bird
Thanks very much Ed for picking up the missing '*' in the ECL spec. You're right - Confluence seemed to be treating these as though they were marking text to bold. I suspect this crept in silently when Confluence was upgraded a few months ago.
I have fixed this in the web version ... and will regenerate a new PDF in the next week or so. Thanks!
Michael Lawley
I'm with Ed on this one. While Harold's observation might be good in an authoring/editorial or academic context, in a clinical context I think it could be quite detrimental.
What I would suggest is that there is a formally informal agreement that /* */ style comments be used in documentation, examples, etc, but that they are not valid in a clinical context and thus that they should be excluded from the normative syntax.
Harold Solbrig
The SKOS specification provides a useful hierarchy of comment types including: skos:changeNote, skos:definition (which some of us don't believe belongs in this hierarchy), skos:editorialNote, skos:example, skos:historyNote and skos:scopeNote. These distinctions have proven to be quite useful in the terminology maintenance process and it would be a shame to not persist this information in the SNOMED CT case. If nothing else, I would propose that we establish an optional? mechanism for including / representing textual definitions and comments in SCG.
Linda Bird
I have added this topic to the agenda for this week's SLPG meeting.
/* It would be great if we could come to an agreed position on this. */
Thanks! Linda.
Peris Brodsky
In programming languages, there are two purposes for an embedded comment syntax. The original, motivating one is to allow internal, localized documentation of subunits of a large program. The second, more frequently purpose (at least for me) is to "comment-out" parts of a program during development.
Both usages have merit for the ECL, certainly. Although the long syntax can help make constraints self-documenting, large or complex constraints need the human touch. And during development of a constraint, the ability to comment-out is essential, especially for those still learning the language.
Though SCG expressions tend to be smaller than ECL constraints, for me the ability to comment-out has been nearly as important while developing logic to operate on them (an ECL executor, for example). There may be use cases for documenting SCG expressions, but I'm not aware of any, and that wasn't my motivation for this proposal.