code-brainstorming

Code Brainstorming

This is a brainstorm for the code microformat. See also examples of code in the wild.

The Problem

There are numerous sites on the Internet that seek to:

• Teach a programming language
• Document a programming language
• Collect examples or bits of code for reuse in the general community
• Show off a particularly interesting section of code.

Examples are:

• tutorials
• language documentation
• programming communities
• blogs.

Each of these sites encapsulates their source code in different fashions and wraps up the metadata in different ways, this makes the source code found around the web largely indigestible by machines.

So by consolidating common practices into a standard format, you a) allow web developers a standard representation of source code online, and b) offer it in a format that is digestible by computers. This more than anything allows for interesting use by users. It would for instance allow users to collect code examples from the web and store them on their local machines in meaningful ways, which in turn allows them to organize and search that new source code repository for examples, classes or snippets that relate to their problem, and further gives them the information necessary to safely use that source code (license, author, language, etc.)

Elements that come up often in practice

Base Elements

• module_title
• author(s) (might be a list)
  • this should probably be an hcard
  • author's name
  • author's webpage
  • author's email
• license (might be a link or written out)
• description (one liner)
• source-code (should always be plain-text with no additional markup)
• module_version (of source code)
• module_date (last updated)
• program-language (perl, php, python, etc.)
  • language-version (5.8, 4, 2.4)
• module_url (linking back to the source of the module)
• category(s)
  • a list of rel-tags

Additional Suggestions

(X)HTML already contains a number of elements relevant to marking up code:

• <code> - for marking up an area of source code. (In the wild I've seen the class attribute on it often used to indicate the programming language.)
• <var> - for marking up a variable. (Not used very often for variables within <code>, but useful for, say, describing command-line parameters taken by a script.)
• <kbd> - for sample input to a program.
• <samp> - for sample output from a program.
• <blockcode> (XHTML2 only) - same semantics as <code>, but a block element with a similar presentation to <pre>.

Although there is probably some value in a code microformat, the effort should be careful to reuse these existing elements before inventing new methods of marking up code.

See also

• code-examples