HotComments is a pattern that gets employed when somebody needs a way to extend a non-extensible format. For example, suppose you have a fixed format containing name, address, etc., and suddenly there is a crushing need to store the GPS coordinates of their mailbox too. You add a hot comment:

Name [delimiter] address [delimiter] ...  ; !GPS=(X,Y,Z)

Old applications that don't know about GPS will still be able to parse it. However, you have now ruined the semantics of comments. They were supposed to be uninterpreted data. Now they are interpreted. Instead of being able to discard comments, your parser now needs to scan through them looking for the magic trap door sequences that signal additional information.

If you find yourself doing this, it is time to switch to an extensible format. ''XML, anyone?'' See XmlSucks...

----

'''Examples'''

* JavaDoc comments in JavaLanguage source code. Most of the JavaDoc tags are ignored by the compiler, which still must process them in order to properly handle the @deprecated tag.

* MacromediaDreamweaver uses HotComments in HTML as markers for the start/end of template sections, and refuses to let you edit the templated parts. [This is a common pattern for extending HTML. Who needs a ContentManagementSystem when you can embed metadata in comments?]

* PostScript has always used them to embed machine-readable directives ('%%' comments); see Adobe Document Structuring Conventions http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf , EPS format spec http://partners.adobe.com/public/developer/en/ps/5002.EPSF_Spec.pdf , etc. -- TobyThain

* Annotating that return values are 'never reached' for 'lint' tools.

* ConditionalComment in Microsoft HTML and scripting languages, like JScript. They are effectively a form of IfDef for JavaScript and HTML. See http://en.wikipedia.org/wiki/Conditional_comment

* DelphiLanguage and FreePascal put compiler directives in comments.

* The SPARK language is a syntactic subset of AdaLanguage and uses comments for annotations that add additional information about what something actually does.

'''A non-example'''

* Embedded DocumentTypeDefinition''''''s look like HotComments, but aren't. A DTD is specified in an SGML DOCTYPE directive, which, although it begins with <!, isn't a comment in SGML. It's actually <!-- that signifies a comment.

----

'''If you find yourself doing this, it is time to switch to an extensible format. XML, anyone?'''

If you are doing this, you already have an extensible format.

''Not really. You have a perversion of the original format that has been extended through BruteForceAndTotalIgnorance, otherwise known as the BFATI (pronounced "buff-fat-ee") Method.''

An extensible format is an extensible format. You have a format and you have extended it, therefore you have an extensible format. I'm not sure how force is measured in this behavior or what categorizes a force as "brute force". "Total ignorance" is just name calling. I've seen elegant uses of HotComments that I wouldn't describe as brutish or ignorant. I've seen inelegant uses of XML that fit both of those pejoratives.

Nope, I would say that you have not extended the format, but changed it (or indeed broken it). Some of what were comments in your old format will now be interpreted as HotComments in the new version, changing the meaning of your data. (Of course you can introduce HotComments without changing your existing data, but can you guarantee that everyone else using format version 1 has not added a comment which might now get interpreted incorrectly as a HotComment?)

''More like a BigBallOfMud. It's a kludge. It's neither fish nor fowl.''

Not a problem. Most things are kludges and big balls of mud. Very little is precisely fish or fowl. Let go.

''Remind me not to use software you maintain.''

HotComments, comments in general, XML and many other things are all examples of the EscapePattern. HotComments are really an escape (from human-readable to machine readable format) embedded within an escape (from machine readable to human readable format).

-------

'''Programming Language Support for Annotations'''

The above suggestion that ''"If you find yourself doing this, it is time to switch to an extensible format"'' has merit. A proper extensible format will automatically be verifiable (e.g. checking that it parses, potentially validating against an extensible schema), have editing support, allow transformations without data loss (losing HotComments), etc. by the same tools used to produce and manipulate the original data. Given a language with support for limited preprocessing or evaluation, that same degree of preprocessing or evaluation for the extensions. HotComments do not provide these features, and are, therefore, a substandard solution.

But HotComments are still ''a'' solution, and sometimes they're the only practical solution. One might be able to write a quick script to translate a CSV to XML, but much harder would be converting a program written in a non-extensible format (a non-extensible programming language) to an ExtensibleProgrammingLanguage. 

And it isn't even that simple. Not every ExtensibleProgrammingLanguage supports the ''right sort'' of extensions for this job. 

We need extensions that aren't processed by the compiler: documentation, classifications for code to help search it (e.g. to locate all event handlers), presentation details (fonts, colors) for LiterateProgramming, guesstimated profiles for the optimizer, marks for 'optional' static verifiers like lint or Emily, etc. An ExtensibleProgrammingLanguage that does fully support these sorts of extensions would be a fine target for pluggable type systems, pluggable optimizers, LiterateProgramming, and post-processor pipelines that could be manipulated from within the language itself (with stages that could perform whole program transforms based on annotations, etc.). 

Language Design Requirements: The language would need to support programmer-introduced ''annotations'' that are simply ignored by the compiler but can be processed by other tools on the backend of the parser. A language that has much syntax would also benefit from an extensible syntax, such that the annotations can be included by code that looks like a genuine part of or variation on the original language (as opposed to appearing kludged in). Since programmers need the ability to process the output from the parser, said output will need to be in a standard format, suggesting that the language will be (at least to a limited degree) a HomoiconicLanguage. The output would traditionally be an AbstractSyntaxTree, except in this case with standard format, but it is also possible to have a result with more processing and partial evaluation so long as the annotations aren't lost. If the type of the output object is AST, then a post-processor pipeline would be a list of functions from AST->AST, potentially with the ability to also return warnings and errors. LiterateProgramming might take AST->PostScript.

Tools, such as IDEs, developed to process the language would probably import the parser then include their own back-end (e.g. an IDE might use the AST to highlight the original source-text, aide with searches, and provide hovertext associated with certain areas of code).

Related: AnnotationMetadata

-------

Yeah, this works great after you have a system that depends on having content in a comment, and then someone else does the same thing with different content in the comment, and now both systems are mutually incapable of parsing this supposed 'extensible' format.

''Use two comments. Each system ignores comments it doesn't understand. Problem solved.''

Then... what do you do about name collisions? (same comment has different meaning) then... you have to add a namespaces capability? 
------
Backward-compatibility or lacking command jurisdiction to change the format are common reasons to apply kludges. It's messy, but that's life. Put in your recommendation for a better format, and if it's rejected, that's that. Move on.

''In other words: what are you all hanging around here debating for? Stop trying to make things better!''
----
See DataCodeEquivocationConsideredHarmful, CategoryXml (for a fix)

(And note this is not a AntiPattern exactly - just a source of abuse that can lead to one. For example, JavaDoc comments are still comments, so they are not as icky as, say, twiddling your compiler settings out of a comment...)

----
CategoryAntiPattern