Annotation (programming)

Annotations (from the Latin for "note") are a means of structuring of program source code , in which the production is automated program text and the programming associated auxiliary files partially. Information from the source text called metadata or meta information, comments and comments or attributes is used as the information basis for the automatic generation of the additional files . The information is ignored when the compiler translates it .

Programming languages that enable this type of integration of meta information include Java , C # and VB.NET . With the help of additional tools, meta information can also be embedded in languages if their syntax does not explicitly support this. The metadata is then usually hidden from the compiler in comments and evaluated with the additional tools.

Attributes in C # and VB.NET

In C # and VB.NET, metadata is mapped in the form of attributes. Attributes can be specified for assemblies, classes, structures, methods, parameters, fields, and enumerations. Each individual attribute is specified in square (C #) or angle brackets (VB.NET) in front of the respective language element. Attribute parameters are used in the same way as parameters of methods and properties.

The following example shows how the attributes are used Obsoleteto mark outdated code and DllImportto include unmanaged (native) assemblies via COM interop.

// Eine Methode (hier Foo) als veraltet markieren.
// Der Parameter vom Typ System.String wird u.&nbsp;a. von IDEs als Hinweistext verwendet.
[Obsolete("Verwenden sie die Methode Bar.")]
public void Foo(string stringParam)
{
    //...
}

// Import der Win32 MessageBox.
// Der Konstruktor von DllImport nimmt hier ein Argument entgegen ("user32.dll"),
// die Klasse DllImport verfügt über eine Eigenschaft CharSet, der ein Wert zugewiesen wird.
[DllImport("user32.dll", CharSet = CharSet.Unicode)]
public static extern int MessageBox(IntPtr hWnd, String text, String caption, uint type);

In addition to the standard attributes that the .NET framework provides, it is also possible to define your own attributes. To do this, you have to create your own class that System.Attributederives from.

The following example shows the definition of a simple attribute Autor:

// Definieren des Attributs "Autor"
[System.AttributeUsage(System.AttributeTargets.Class |
                       System.AttributeTargets.Struct)
]
public class Autor : System.Attribute
{
    private string _vorname;
    private string _nachname;

    public Autor(string vorname, string nachname)
    {
        _vorname = vorname;
        _nachname = nachname;
    }
}

// Verwenden des Attributs "Autor"
[Autor("Max", "Mustermann")]
class BeispielKlasse
{
    //...
}

Annotations in Java

With Javadoc and the annotations, the Java programming language provides two mechanisms for integrating metadata. These are used in particular in the J2EE environment to automatically generate various files. These include, for example, SQL files, deployment descriptors and the interfaces connected to Enterprise Java Beans (remote interface, home interface ...).

Javadoc

Javadoc is a tool for evaluating comments in the source code that was introduced with Java 1.2. For this purpose, comments that are to be evaluated are introduced with the character string /**. Special tags can then be used within these comments and each assigned a character string as a value.

The evaluation is carried out using the Javadoc tool of the same name, which was originally designed for automated source code documentation. Another possibility is the XDoclet used in the J2EE environment in particular . The following example shows how to specify the software version using Javadoc:

 /**
  * @version 1.5
  */
public class A {}

Annotations (from Java 5)

With the language version Java 5, annotations were created as a separate language element. Annotations are identified in the source text by an @ sign followed by the name of the annotation. It is also possible to transfer parameters to annotations. You can also add your own annotations to the given annotations.

Annotations can be evaluated using the Annotation Processing Toolkit (APT) directly in the source text or by means of reflection during the runtime of a program. Among other things, this creates further possible uses compared to Javadoc. For example, the compiler itself evaluates some annotations. The following example shows how to suppress a compiler warning using the appropriate annotation:

 public class A {
   @SuppressWarnings("unchecked")
   public void meineMethode() {}
}

As of Java 6, the APT tool is already integrated in the Java compiler. As of Java 8, the APT tool is no longer delivered separately.

Individual evidence

↑ Microsoft Developer Network: Attributes (C # and Visual Basic). Retrieved November 29, 2011 .
↑ MSDN: Creating Custom Attributes (C # and Visual Basic). Retrieved November 29, 2011 .

[1] Microsoft Developer Network: Attributes (C # and Visual Basic). Retrieved November 29, 2011 .

[2] MSDN: Creating Custom Attributes (C # and Visual Basic). Retrieved November 29, 2011 .