Ted Leung on the air
Ted Leung on the air: Open Source, Java, Python, and ...
Ted Leung on the air: Open Source, Java, Python, and ...
Sun, 31 Aug 2003
Comments as metadata
Oliver Steele has a
long post categorizing the various uses of comments. Along the way, he stratifies macro systems into structural macros and definition-level macros, and relates those to explict programming.
He concludes with a section about comments intended for comment processors like doctest, iContract, and XDoclet.
[00:50] |
[computers/programming] |
# |
TB |
F |
G |
0 Comments |
All of these functions of comments as metadata could be implemented by extending the language instead. (Contracts are from Eiffel, for example, which supports them in its core syntax.) However, the use of structured comments as metadata lets a third-party tool address a gap in the language in a way that leaves the source structure intact for compilers and other source processors (such as editors, source debuggers, and refactoring tools) that wouldn't recognize an extended grammar. Just as comments are an escape hatch for human readers, they're an escape hatch for development tools as well. And these two kinds of comments - natural language and structured metadata - are related. They both add information that can't be expressed in the primary programming language. And they're both useful to humans too.
You can subscribe to an RSS feed of the comments for this blog:
Add a comment here:
You can use some HTML tags in the comment text:
To insert a URI, just type it -- no need to write an anchor tag.
Allowable html tags are:
You can also use some Wiki style:
URI => [uri title]
<em> => _emphasized text_
<b> => *bold text*
Ordered list => consecutive lines starting spaces and an asterisk
To insert a URI, just type it -- no need to write an anchor tag.
Allowable html tags are:
<a href>
, <em>
, <i>
, <b>
, <blockquote>
, <br/>
, <p>
, <code>
, <pre>
, <cite>
, <sub>
and <sup>
.You can also use some Wiki style:
URI => [uri title]
<em> => _emphasized text_
<b> => *bold text*
Ordered list => consecutive lines starting spaces and an asterisk