A post by Wes reminded me of an idea I had back in March 2001. After some discussion on the DevelopMentor mailing list (I think there was just the one .NET list back then) I wrote up a summary and gave it the rather grand sounding name of MetaCode. Here it is…
What is MetaCode?
The MetaCode vision
Source code of today is, for the most part, plain text. We all bash away at
our notepad-derived text editors, struggling to format our code, keep it
syntactically correct, and place useful comments within it. This is hard work.
Developing software is hard enough without these extra chores.
MetaCode attempts to reduce the
complexity of this juggling act by allowing the developer to concentrate on the
logical structure of the code. Formatting, code documentation, and validity checking
"just happen". The MetaCode vision is of a completely new
representation of code. XML is the technology which makes this possible.
I’d like to explain further by talking about each part of the problem in
turn.
Code
Code has structure. Code is structure. Our namespaces contain classes
contain methods. Why, then, do we continue to use plain text for our source
code? Plain text has no structure.
Developers put a lot of effort into trying to represent structure in plain
text source code. We spend too much time indenting blocks, making sure our curly brackets line up, word wrapping
our comments, and generally making things look acceptable. This is a lot of
wasted effort. Still, when we’re done we have our nicely formatted, commented
source code.
What do we do then? We hand our pretty source code to a compiler which
promptly strips out all of our comments and formatting so that it can
concentrate on the semantics of the code. So, the compiler doesn’t care how our
code looks; if we can somehow overcome our own need to have beautiful code then
we can save ourselves a lot of trouble.
Why do we feel the need to format our code? What do we get for our efforts?
- Structural information. We use indentation to show the structure of our
code. This helps us understand how our code works when we are reading it.
- Documentation. We get information about the code where we need it most -
with the code.
- RSI
How can we get these benefits without formatting our code? The structure we
need exists in our code whether we choose to show it in formatting or not. Why don’t we use
this built in structure instead of attempting to duplicate it with our
formatting?
XML has proven itself as a syntax for representing hierarchical data in a
textual format. We can use XML to represent our code.
For example, take the following code snippet:
class MyClass : BaseClass
{
// This method returns a number. It isn't a very useful example.
int MyMethod()
{
return 0;
}
}
We can represent the same information like this:
<class name="MyClass" base="BaseClass">
<method name="MyMethod" type="int">
<description>
This method returns a number. It isn't a very useful example.
</description>
<body>
return 0;
</body>
</method>
</class>
At first it appears that all we have done is sacrifice some readability. But,
we have gained the ability to read, understand and create our code in other
ways. We can:
- Read our code with any XML parser - this makes writing code to manipulate
code very easy
- Process our code with XSLT to produce our original plain text source code,
ready for compilation
- Process our code with XSLT to produce documentation
- Edit our code with an XML editor such as XML Spy which can understand and enforce the structural rules of our code
as we edit it
So, MetaCode replaces the structural syntax of the programming language with a
standard, simple, widely accepted structural syntax; XML.
Documentation
I touched briefly on documentation a moment ago. However, the problems and
potential benefits in this area are worth further discussion.
We try to document our code in several ways:
- We add comments to our source code. Comments are difficult to format, are
restricted to plain text, and are difficult to find and read. These problems
tend to sap the developer of his good intentions, and they are either omitted
or become out of date.
- Because our code comments are inadequate, we attempt to maintain separate
documents describing the code. These supporting documents are invariably out of date.
- Ideally, we produce a UML model of our code. In my experience, unless your
UML tool makes round trip engineering effortless, this suffers from the same
problems as supporting documentation.
MetaCode addresses these problems by combining the code and its documentation
into the same document. This brings the following benefits:
- The documentation is always complete, accurate, and up to date.
- Much of the valuable documentation describes the structure of the code. We
no longer need to document this as we can generate our documentation from the
code itself.
- We can annotate our code with any XML data we like - so we can embed XHTML
(or anything else) if we wish to go beyond the plain text we are stuck with
today.
Of course, there is nothing to stop you continuing to write supporting
documents and UML models.
Example
Here’s the ever popular Hello World program in MetaCode for C#:
<namespace name="Microsoft.Samples.WinForms.Cs.SimpleHelloWorld">
<using namespace="System"/>
<using namespace="System.WinForms"/>
<class visibility="public" name="SimpleHelloWorld" base="Form">
<method visibility="public" static="true" return="int" name="Main">
<summary>
The entry point for the application.
</summary>
<parameter type="string[]" name="args"/>
<body>
Application.Run(new SimpleHelloWorld()); return 0;
</body>
</method>
<method visibility="public" name="SimpleHelloWorld">
<summary>
Does something really useful.
</summary>
<body>
this.Text = "Hello World";
</body>
</method>
</class>
</namespace>
Conclusion
MetaCode replaces traditional structural syntax with XML. This allows code
structure to be processed by the multitude of XML tools available today, and
makes writing new, specialist tools trivial. It encourages good documentation by
providing a consistent, logical place to write annotations alongside code.