Why Annotations?

annotations node javascript
April 06, 2013

#It’s all about describing code

An annotation is a note that is made while reading any form of text.

Annotations are used as a special form of syntactic metadata in the source code. The term metadata refers to “data about data”. While it is an ambiguous definition, the concept in CocktailJS is used to describe actions performed over a class or object . We need “metadata” to perform those actions but at the same time they describe -or annotate- the code.

Let’s see an example:


cocktail.mix(MyClass, {
    '@extends': Base,
    '@properties': {
        text: 'some text'
    },

    //...
});

In the example above, we’ve annotated MyClass with two annotations, ‘@extends’ and ‘@properties’. MyClass extends from Base, and it has a property named text.

Basically, any property that starts with @ defined in the second parameter in cocktail.mix method, is treated as an annotation. cocktail.mix() will read every annotation and perform the associated action.

##The ‘@’ symbol The @ symbol is not a valid indentifier. We have to define the annotations between quotes:


'@extends': Base,

This is not just a workaround. When you read code you can easily detect a property name defined between quotes. It gives the sensation that those properties don’t belong to the code, which is the idea behind the annotation concept.

##Advantages

These are some of the advantages of having annotations in cocktail and they are part of the library goals.

##Do one thing and do it well cocktail delegates all the work to its annotations so each of them can do a very simple and small action, even though sometimes it is not that small or simple.
The goal behind a particular annotation should be concise and very well defined.

comments powered by Disqus