Funktions­beschreibung und Datei­header automatisch generieren per Makro

Letztes Update: Dienstag, 16. August 2016 - 16:41 Uhr

Auf dieser Seite möchte ich zwei kleine Makros für Microsoft Visual Studio .NET 2003 vorstellen, die das Dokumentieren bei der C/C++ Programmierung etwas erleichtern ("Function Comment Macro" and "File Purpose Comment Macro").
(Ich hatte die ewigen Copy & Paste Mühen und die unnötige Tipparbeit satt.)
Weiter unten gibt es eine kurze Anleitung, um das Visual Basic Script in Visual Studio .NET 2003 einzubinden. Das Tool kann dann bequem per Tastenkombination oder über eine neue Buttonleiste aufgerufen werden.


Beschreibung des Makros "Generate­File­Comment()"

Typischerweise beginnen alle Quelltextdateien in einem Projekt mit einem Kommentarblock, der den Inhalt der Datei, Name und Zweck, Erstellungsdatum usw. enthält. Dieses Makro erzeugt diesen Block automatisch am Anfang der aktuell geöffneten Datei.

Beispiel für einen erzeugten Dateikopf (File header):

//---------------------------------------------------------
// My company name or private copyright notice
//
// Filename:     test.cpp
// Created:      2005-12-04 (17:52), by Andreas Schibilla
// Purpose:
//
// Coypright(c): Andreas Schibilla
//---------------------------------------------------------

 

Beschreibung des Makros "Generate­Function­Comment()"

Auch vor jeder Funktionsdefinition sollte ein Kommentarblock stehen, der die Funktion, die Parameter, den Rückgabewert usw. erläutert.
Dieses Makro erstellt diesen Kommentarblock mit der Funktionsbeschreibung automatisch, so dass nur noch die wesentlichen Angaben hinzugefügt werden müssen.

Funktionsweise 1:

Der Cursor wird einfach in die Kopfzeile der Funktion gesetzt, dann wird das Makro gestartet, der Kommentarblock wird automatisch eingefügt.

Beispiel:
Befindet sich der Cursor irgendwo in der untenstehenden Zeile:

int test(int a, void *pointer , unsigned int my_funny_array[] )

So erzeugt das Makro den neuen Text:

//------------------------------------------------------------------
// Function:     test()
// Description:
// Returns:      -
//
// Parameters:
// [->] a              -
// [->] pointer        -
// [->] my_funny_array -
//
// Created:      2005-12-04 (18:55), by Andreas Schibilla
//------------------------------------------------------------------
int test(int a, void *pointer , unsigned int my_funny_array[] )


Funktionsweise 2:

Geht der Funktionskopf über mehrere Zeilen, so muss der komplette Funktionskopf entsprechend markiert werden, bevor das Makro gestartet wird.

Beispiel:
Die untenstehenden drei Zeilen sind markiert:

template
T maximum( T const a,
           T const b ){ return a > b ? a : b; }

Das Makro erzeugt dann den Textblock:

//------------------------------------------------------------------
// Function:     maximum()
// Description:
// Returns:      -
//
// Parameters:
// [->] a -
// [->] b -
//
// Created:      2005-12-04 (19:05), by Andreas Schibilla
//------------------------------------------------------------------
template
T maximum( T const a,
           T const b ){ return a > b ? a : b; }


Funktionsweise 3:

Wenn eine Funktion bereits einen Beschreibungstext hat, kann durch erneutes Aufrufen des Makros ein "Modified" mit aktuellem Datum hinzugefügt werden.

Beispiel:
Der Cursor befindet sich irgendwo in der untersten Zeile (beginnend mit "void MyClass...") des folgenden Codeausschnitts:

//------------------------------------------------------------------
// Function:     MyFunction()
// Class:        MyClass
// Description:  Some text to explain function
// Returns:      -
//
// Created:      2005-12-04 (19:09), by Andreas Schibilla
//------------------------------------------------------------------
void MyClass::MyFunction()

Dann erzeugt ein Aufruf des Makros den zusätzlichen "Modified-Eintrag":

//------------------------------------------------------------------
// Function:     MyFunction()
// Class:        MyClass
// Description:  Some text to explain function
// Returns:      -
//
// Created:      2005-12-04 (19:09), by Andreas Schibilla
// Modified:     2005-12-04 (19:12), by Andreas Schibilla
//------------------------------------------------------------------
void MyClass::MyFunction()

 


Download, Installation und Einrichtung der Makros (inkl. Tastenkombination und Buttonleiste)

Zu Beginn muss die Makro-Datei "CommentGenerator.vb" downgeloadet und abgespeichert werden:

Downloads:

Download des Macros (Visual Basic Textdatei, 20 KB)
Download des Macros mit zwei zusätzlichen Icons (ZIP-Format, 4 KB)(Thanks to SMR!)

Installation des Makros:

  1. Visual Studio .NET 2003 ist gestartet, ein Projekt geöffnet und eine Quelltextdatei wie z.B. "test.cpp" im Editor aktiv.
  2. Über den Menüpunkt "Extras -> Makros -> Makro-IDE" oder die Tastenkombination "Alt+F11" muss die Makro-Umgebung gestartet werden. Sie erscheint in einem neuen Fenster:
    Visual Studio .NET 2003 Macro-IDE
  3. Dort kann die Visual Basic Datei einem Modul wie z.B. "MyMacros" hinzugefügt werden. Dazu muss zunächst das Modul "MyMacros" per Linksklick ausgewählt werden, dann kann über den Menüpunkt "Projekt -> Vorhandenes Element hinzufügen..." die Datei angegeben und geöffnet werden.
  4. Die Konstanten "C_AUTHOR_NAME", "C_COPYRIGHT_NAME" und "C_LOGO_LINE1-4" sollten den eigenen Vorstellungen entsprechend gesetzt werden. Natürlich kann auch das Script individuell angepasst werden!
  5. Nachdem "MyMacros" gespeichert wurde, kann die Macro-DIE wieder beendet werden. Das Macro steht nun als Befehl zur Verfügung!

Integration in die Symbolleiste und Zuweisen von Tastenkombinationen:

  1. In Visual Studio kann per Rechtsklick auf eine Symbolleiste das Kontextmenü geöffnet werden, der Menüpunkt "Anpassen" öffnet einen neuen Dialog.
    Dialog: Anpassen
  2. Im Tab-Reiter "Symbolleisten" kann jetzt über den Button "Neu..." eine neue Leiste erzeugt werden. Eine leere Symbolleiste erscheint.
    Leere Symbolleiste
  3. Im Tab-Reiter "Befehle" kann die "Kategorie" Makros angewählt werden, unter dem Namen "MyMacros.CommentGenerator..." verbirgt sich das neue Makro. Per Drag & Drop kann der Befehl in die neue Symbolleiste gezogen werden.
    Befehl per Drag & Drop hinzufügen
  4. Per Rechtsklick auf der neuen Symbolleiste lässt sich der neue Button in der Symbolleiste konfigurieren. Der Name lässt sich ebenso einstellen wie das Icon.
    Button konfigurieren
  5. Im gleichen Dialog "Anpassen" können über den untenstehenden Button "Tastatur..." auch Tastenkombinationen für das schnelle Aufrufen der Makros eingerichtet werden.
    Tastatur Shortcuts Tastaturkombinationen definieren

Wenn alles geklappt hat, sieht die neue Symbolleiste etwa so wie in der unteren Abbildung aus:

Fertige Symbolleiste

 

Kommentare 2

Daniel (2012-07-09 - 07:50 Uhr)
Ich habe Ihr Makro für die Kommentierung mit dem VS2005 ausprobiert.

Es ist bei der Hälfte der Zeilen immer abgestürzt und da habe ich mal ein bisschen debugged. Der Grund für die Abstürze lag nur in einer einzigen Zeile. Jetzt funktioniert es tadellos und ich bin begeistert davon. Genau sowas habe ich immer gesucht.

Ich wollte Ihnen die Änderung mitteilen, damit Sie es vielleicht aktualisieren.

Also, die Funktion WriteLn muss folgendermaßen lauten:

' Eine Zeile in das Editorfenster schreiben
Function WriteLn(ByVal strIn)
ActiveDocument.Selection.StartOfLine()
ActiveDocument.Selection.Insert(strIn)
ActiveDocument.Selection.NewLine()
End Function

Gruß, Daniel
Nici (2013-01-23 - 13:23 Uhr)
Ich verwende die Makros in VS2008. Funktionieren super, danke!

 

Neuen Kommentar abgeben

npts8