Mit Kommentaren und zusammengesetzten Anweisungen arbeiten
Wenn Sie Code für eine Programmiersprache schreiben, empfiehlt es sich, Ihren Code zu kommentieren. Ein Kommentar ist eine Beschreibung oder zusätzliche Erklärung zu Ihrem Code innerhalb ihres Codes. Kommentaranweisungen gelten nicht als Codierung. Die Anweisungen sind nur verfügbar, damit andere Entwickler den von Ihnen geschriebenen Code besser verstehen können.
Sie können zwei Schrägstriche (//) verwenden, um wie folgt zu kommentieren:
// This is a comment
In Visual Studio Code können Sie Bearbeiten und dann Zeilenkommentar umschalten auswählen (oder verwenden Sie die Tastenkombinationen Strg +:) zum Kommentieren.
Sie können /* und */ verwenden, um einen ganzen Codeblock kommentieren.
In Visual Studio Code können Sie Bearbeiten und dann Blockkommentar umschalten zum Kommentieren eines Codeblocks auswählen (oder verwenden Sie die Tastenkombinationen ALT+UMSCHALT+A).
/* This is a comment
on multiple
multiple
multiple
lines. */
XML-Kommentare im Code
In Dynamics 365 Business Central können Sie Ihrem Code eine Dokumentation hinzufügen, indem Sie XML-Elemente in speziellen Kommentarfeldern direkt im Quellcode vor dem Codeblock einfügen, auf den sich der Kommentar bezieht.
Der Dokumentationskommentar muss unmittelbar vor einem benutzerdefinierten Typ stehen, den er kommentiert, z. B. eine Codeunit, eine Tabelle oder eine Schnittstelle oder ein Mitglied wie ein Feld oder eine Methode.
Die Syntax für das Hinzufügen von XML-Kommentaren in Ihren Code lautet dreifache Schrägstriche /// gefolgt von einem der unterstützten XML-Tags.
Es gibt IntelliSense-Unterstützung für das Schreiben von Dokumentationskommentaren. Beim Schreiben des dritten Schrägstrichs der dreifachen Schrägstriche ist es besonders wichtig, einen Vorlagendokumentationskommentar bereitzustellen.
Dokumentationskommentare sind sichtbar, wenn Sie in Vervollständigungslisten und in der Signaturhilfe mit der Maus auf die Quellsymbole zeigen.
Indem Sie dem Code XML-Kommentare hinzufügen, können Sie die Lesbarkeit verbessern, nützliche Informationen über die Implementierung hinzufügen und anderen helfen, den von Ihnen geschriebenen Code zu übernehmen. Mit XML-Kommentaren aktivieren Sie IntelliSense in Visual Studio Code für die AL-Objekte, die Sie Ihrem Code hinzufügen, um anderen Entwicklern zu helfen, mit Ihrem Code zu arbeiten oder ihn zu erweitern. Wenn Sie also eine Erweiterung erstellt haben und ein Benutzer diesen Code erweitert, erhält er beim Aufrufen des entsprechenden Objekts eine Inlinedokumentation.
Weitere Informationen finden Sie unter Unterstützte XML-Tags.
Das folgende Beispiel stammt aus der Datei „Email.Codeunit.al“ in der Systemanwendung. In diesem Beispiel wird der Parameter „EmailMessageId“ mit der <param>-Syntax dokumentiert.
/// <summary>
/// Provides functionality to create and send e-mails.
/// </summary>
codeunit 8901 "Email"
{
Access = Public;
/// <summary>
/// Enqueues an email in the outbox to be sent in the background.
/// </summary>
/// <param name="EmailMessageId">The ID of the email to enqueue</param>
procedure Enqueue(EmailMessageId: Guid)
begin
EmailImpl.Enqueue(EmailMessageId);
end;
...
Verwenden Sie die HTML-Codierung < und >, die < bzw. > entspricht, damit spezielle Symbole wie spitze Klammern im Text eines Dokumentationskommentars angezeigt werden.
Das folgende Beispiel veranschaulicht die Vorgehensweise.
/// <summary>
/// This property always returns a value < 1.
/// </summary>
Codekommentare verbessern die Lesbarkeit des von Ihnen entwickelten Codes und sind sehr hilfreich für alle, die diesen Code ändern oder warten. Zudem Code-Kommentare aus der automatisch generierten Dokumentation.
Großartige Codekommentare entsprechen Folgendem:
Sie sagen nie das Offensichtliche
Schreiben Sie einen aussagekräftigen Kommentar, und verwenden Sie präzise Formulierungen, um zu beschreiben, warum.
Stellen Sie sich vor, Sie befinden sich in der Rolle des Entwicklers, der diesen Code verwendet. Was möchten Sie wissen?
Verwenden Sie für Eigenschaften und Methoden aktive Formulierungen wie Sets ..., Gets ... und Specifics ... und erklären Sie dann, was es tut.
Listen Sie alle Vorbedingungen für Ihre Parameter auf (können nicht gleich Null sein, müssen innerhalb eines bestimmten Bereichs liegen usw.).
Listen Sie alle Nachbedingungen auf, die beeinflussen könnten, wie Aufrufer Rückgabewerte verarbeiten.
Listen Sie alle Ausnahmen auf, die von der Methode ausgelöst werden können (und unter welchen Umständen).
Wenn es ähnliche Methoden gibt, erklären Sie die Unterschiede.
Lenken Sie die Aufmerksamkeit auf etwas Unerwartetes (z. B. das Ändern des globalen Status).
Nennen Sie alle Nebenwirkungen, falls es welche gibt.
Seien Sie konsistent und prägnant.
Stellen Sie sicher, dass Ihre Kommentare überprüft werden.
Compiler-Direktive für Coderegionen
Verwenden Sie Coderegionen, um zusammenhängenden Code zu strukturieren, fügen Sie die Dokumentation von Codeabschnitten hinzu, und erweitern oder reduzieren Sie diese für eine schnelle Navigation in Ihrem Code mit einfacher Gliederung des Codes.
Direktiven ist ein neues Konstrukt in der AL-Sprache, das festlegt, wie der AL-Compiler einen umschlossenen Codeabschnitt behandelt. Das gleiche Konzept ist in anderen Sprachen bekannt. Die spezifischen Direktivanweisungen müssen vom Compiler unterstützt werden – Sie können keine benutzerdefinierten Vorverarbeitungsanweisungen erstellen.
Die Direktive #region wird verwendet, um einen Codeblock zu markieren, den Sie erweitern oder reduzieren können. Dies kann beispielsweise bei größeren Dateien zur besseren Lesbarkeit oder zur Konzentration auf den Code nützlich sein, an dem Sie gerade arbeiten. #endregion gibt das Ende eines #region-Codeblocks an.
Ein #region-Block muss mit einer #endregion-Direktive beendet werden. Ein #region-Block darf sich nicht mit einem #if-Block überschneiden. Ein #region-Block kann in einen #if-Block und ein #if-Block kann in einen #region-Block geschachtelt sein.
In diesem Beispiel macht die #region-Direktive einen für die Umstrukturierung vorgesehen Codeblock reduzierbar:
#region Ugly code - let's not look at this
procedure UglyCode()
begin
// No one should look at this
end;
#endregion
Beispiel für die Definition von Bereichen in einer Codeunit:
Beispiel für das Reduzieren von Bereichen:
Zusammengesetzte Anweisungen
Eine zusammengesetzte Anweisung ist eine Anweisung, die aus mehreren Anweisungen besteht. Zusammengesetzte Anweisungen sind durch Anfang und Ende gekennzeichnet. Alles dazwischen ist eine zusammengesetzte Anweisung.
begin
statement 1;
statement 2;
statement 3;
...
end