A literal %> in a usage example, sitting inside a JScript block comment in a new include prototype, would have ended the script block early. The legacy application scans for those boundaries before it ever parses the comment. We caught it while writing the header, and removed the delimiter before the file was used.
Here is the setup. We were building a drop-in feature-gate include for an existing module. It needs a good header comment, because other pages drop it in and call it. The file opens with <% and a JScript block comment, /* ... */, holding the documentation. The natural thing to put in that block is a worked example: the include line, then how you call it. We pasted in a <!--#include ...--> line and a snippet showing <% if(!featureCheck.isEnabled('feature-name')) { ... } %>. The idea was to show people the delimiters so they know it is server script.
That snippet was the problem. What looked like an inert documentation block was carrying a real template boundary token. Not the logic, not a typo: just a documentation example with a %> in it.
The comment never gets a vote
The instinct, and it is a reasonable one, is that a comment is inert. You wrap text in comment syntax and the engine ignores it. In most languages that holds, because the comment is recognized during parsing as a unit, and its contents never get tokenized as code.
In this older web application, the <% and %> delimiters are recognized before the script-language parser has any concept of the comment. The template scanner divides the source into literal output and script regions by looking for the raw delimiters. Only then are those regions handed to the script engine.
So when the scanner is inside a script block and hits %>, that block ends. Full stop. It does not matter that, three lines up, a human reading the source would say “obviously this is a comment, it is documentation.” The tokenizer has not reached the point where comment-ness exists. By the time anything understands a ', a JScript // or a /* */ as “ignore this,” the delimiter has already set the boundaries of the script block. A block comment saves you no more than a line comment does, because both are a parsing-stage concept and the delimiter scan sits upstream of parsing.
The diagnostic habit that falls out of this is to identify which parser owns a boundary first. Other template and embedding systems can have similar edge cases, but their exact delimiter and escaping rules differ, so verify the specific engine rather than importing a rule from this one wholesale.
What we changed in the header
For this include, the safe choice was to keep the literal delimiter sequence out of the file entirely. The scanner sees the raw boundary before JScript escape handling or comment parsing could help.
So we rewrote the usage example in prose, with the delimiters removed. Instead of a runnable <% ... %> snippet, the comment now reads: “include the file, then call: if(!featureCheck.isEnabled('feature-name')) { ... }”. The <!--#include--> line and the wrapping <%/%> are gone. The header even spells out why, in the comment itself: the delimiters are kept out of the example so the parser does not see them as script delimiters when the file is read by grep.
The reader still gets the include name, the call shape, the method and the argument. They lose the copy-pasteable block, and that is the trade. The documentation describes the syntax instead of reproducing it verbatim. That is marginally less convenient, but it beats leaving an unverified delimiter collision in a prototype include. The file never merged to the main branch, so the rewrite removed the risk before it reached a live path.
Where this shows up
A file can pass through more than one parser, and the parser that recognizes outer boundaries may run before the language parser that recognizes a comment or string. When you document syntax inside a processed template file, check that engine’s delimiter rules and avoid literal boundary sequences unless its documentation explicitly supports the context.
These collisions tend to appear in header comments, generated help text, test fixtures and examples embedded in processed files. When we needed to show the server script syntax, we moved the full example to documentation outside the include and described the call shape in the header. That kept the source comment readable without depending on an unverified delimiter trick.
Documentation inside a file that a template scanner processes can break the file, even when it sits in a comment. Before an example containing delimiters goes into such a file, check which parser sees the boundaries first, and keep the full example somewhere the scanner never reads.