Kommentar und Documentation (Engl. Commenting and Documentantion) ([1])
Dokumentation und Kommentar des Quellcodes ist bei seiner Produktion einer der wichtigsten Prozesse. Obwohl sie mit der Codezweckmäßigkeit nicht direkt verbunden ist, ist sie indirekt mit seiner Erweiterungsmöglichkeit verbunden, da sie weitsichtigerweise die Absichten des ursprünglichen Entwicklers deutlich macht.
Für die Dokumentation geeignete Themen umfassen oft:
- Allgemeine Programmschilderung. Sie muss umfassen:
- Einen Überblick über den Zweck, zu dem-wozu das Programm entwickelt wurde.
- Ein einfaches Programmgebrauchsbeispiel.
- Erlernungsanweisungen für den Grundprogrammgebrauch.
- Dokumentation des Quellcodes. Die Dokumentation des Codes umfasst:
- Klassen- und Funktionsschilderung des Programms.
- Den Zusammenhang zwischen den Klassen und Funktionen.
- Für jede Funktion, je nach dem Fall, eine Beschreibung, die Voraussetzungen für ihre richtige Funktion, ihre Ergebnisse, den Rückgabewert sowie mögliche Fehler, die vorkommen können.
- Fehlerlokalisierung und Strategien für Ihre Vermeidung.
- Wie kann das Programm kompiliert und gelinkt werden.
- Die Programmversion und mögliche Änderungen, die gemacht worden sind.
- Begründung für die Planungsbeschlussfassung.
- Irgendein Dankeschön.
Με τα σχόλια και την τεκμηρίωση διασφαλίζεται ότι ο κώδικας έχει περιγραφτεί με επαρκείς λεπτομέρειες έτσι ώστε όταν κάποιος κοιτάζει τον πηγαίο κώδικα θα μπορεί εύκολα να καταλάβει το σχεδιασμό και το σκοπό του κώδικα ([1]).
Generalkommentare ([2],[3],[4],[5])
- Im Allgemeinen müssen die Kommentare im Quellcode beschreiben WAS und nicht WIE sie machen.
- Die besten Kommentare im Quellcode ist der Quellcode selbst. Aus diesem Grund muss sich der Quellcode von selbst belegen. Es ist besser, dass etwas durch den Quellcode an und für sich erklärt wird (z.B. durch den Gebrauch irgendeines komplexen Variablennamens), anstatt später Kommentare zu gebrauchen, die erklären, wozu die Quellcode dient.
- Kommentaren müssen in:
- komplexe,
- nicht offenkundige,
- interessante oder
- wichtige Quellcodestellen aufgestellt werden.
Vor diesen Stellen müssen kleine Kommentare aufgestellt werden, die erläutern, was der Quellcode tut. Zum Beispiel:
// Divide result by two, taking into account that x
// contains the carry from the add.
for (int i = 0; i < result->size(); i++)
{
x = (x << 8) + (*result)[i];
(*result)[i] = x >> 1;
x &= 1;
}
- Wenn sich die Kommentare in ziemlich vielen Linien ausstrecken, kann sie die Ausrichtung leichter lesbar machen. Zum Beispiel:
DoSomething(); // Comment here so the comments line up.
DoSomethingElseThatIsLonger(); // Comment here so there are two spaces
// between the code and the comment.
{ // One space before comment when opening a new scope is allowed,
// thus the comment lines up with the following comments and code.
DoSomethingElse(); // Two spaces before line comments normally.
}
DoSomething(); /* For trailing block comments, one space is fine. */
Entitätskommentare
In diesem Kapitel erwähnt einige von den verbreitetesten Arten, die gebraucht werden, um die Quellcodeentitäten zu erläutern.
Programmdateien
- Jede Datei muss die Quellcodelizenz enthalten (z.B. Apache 2.0, BSD, LGPL, GPL). Die Lizenzauswahl ist sehr eine komplexe Prozedur, die dennoch nicht vernachlässigt werden muss.
- Der Quellcodeautor muss enthalten werden.
- Jede Datei muss einen Kommentar haben, der ihre Inhalte beschreibt.
/*
Copyright (c) 2013, Anagnostopoulos Vasilis-Thanos,
Post-Graduate Student in University of Piraeus.
All rights reserved.
Redistribution and use in source and binary forms,
with or without modification, are permitted provided
that the following conditions are met:
...
*/
/*
This is a program that ...
*/
Variablen
- Im Allgemeinen muss der Variablenname ziemlich beschreibend sein, so dass er dem Entwickler die Möglichkeit gibt, zu verstehen, aus welchem Grund die gewisse Variable gebraucht wird. In bestimmten Fällen braucht man noch einige Kommentare.
// The total number of tests cases that we run through
// in this regression test.
const int k_num_test_cases = 6;
Funktionen (1)
- Jede Funktionsdeklaration muss Kommentare haben, die der Funktion vorausgehen und beschreiben, was die Funktion macht und wie sie gebraucht wird. Im Allgemeinen beschreiben die Kommentare über der Funktionsdeklaration den Gebrauch einer Funktion, während die Kommentare in der Funktionsrealisierung deren Funktionsrolle beschreiben.
- Bei der Funktionsdeklaration müssen folgende Punkte erwähnt werden:
- Die Eingabevariablen und die Variablen, die die Funktion zurückgibt.
- Wenn die Funktion Speicher einnimmt, den der Entwickler frei machen muss (Das ist der Fall in Programmsprachen, wobei sie keinen Speicherabfallsammler besitzen (Εngl. garbage collection), wie C++).
- Εάν κάποια από τις μεταβλητές εισόδου ή εξόδου θα πρέπει να είναι δείκτης στο κενό.
- Εάν υπάρχει οποιαδήποτε επίπτωση στην απόδοση με την χρησιμοποίηση της συνάρτησης.
// Returns an iterator for this table. It is the client's
// responsibility to delete the iterator when it is done with it,
// and it must not use the iterator once the GargantuanTable object
// on which the iterator was created has been deleted.
//
// The iterator is initially positioned at the beginning of the table.
//
// This method is equivalent to:
// Iterator* iter = table->NewIterator();
// iter->Seek("");
// return iter;
// If you are going to immediately seek to another place in the
// returned iterator, it will be faster to use NewIterator()
// and avoid the extra seek.
Iterator* GetIterator() const;
Συναρτήσεις(2)
- Εάν υπάρχει κάποιο πολύπλοκο κομμάτι για το πως μίας συνάρτηση κάνει την
δουλειά της τότε θα πρέπει να υπάρχει ένα επεξηγηματικό σχόλιο στην δήλωση
της συνάρτησης το οποίο θα περιγράφει
- οποιοδήποτε κόλπα χρησιμοποιήθηκαν κατά την δημιουργία της συνάρτησης αυτής,
- θα παρουσιάζει συνοπτικά τα βήματα που εκτελούνται κατά την λειτουργία της συνάρτησης
- και θα εξηγεί γιατί δεν προτιμήθηκε κάποιος άλλος τρόπος υλοποίησης.
- Όταν σε μία συνάρτηση περνιούνται σαν ορίσματα μεταβλητές boolean, ή ακέραιες μεταβλητές, ή κενοί δείκτες θα πρέπει να υπάρχουν σχόλια τα οποία θα επεξηγούν τί κάνουν αυτές οι τιμές.
bool success = CalculateSomething(
interesting_value,
10, // Default base value.
false,// Not the first time we're calling this.
NULL
);// No callback.
Κλάσεις
- Κάθε κλάση πρέπει να έχει ένα συνοδευτικό σχόλιο το οποίο θα περιγράφει την κλάση και πως πρέπει να χρησιμοποιείται.
- Τα μέλη των συναρτήσεων θα πρέπει να έχουν ένα σχόλιο το οποίο περιγράφει την χρήση τους. Ακόμα αν μπορούν να λάβουν τιμές με ιδιαίτερη σημασία θα πρέπει να αναφέρονται στα σχόλια.
- Γενικά ένα αρχείο επικεφαλίδας θα περιγράφει τις κλάσεις που δηλώνονται μέσα στο αρχείο με μία επισκόπηση στο τί κάνει η κάθε κλάση και πως χρησιμοποιείται. Αντιθέτως ένα πηγαίο αρχείο πρέπει να περιέχει περισσότερες πληροφορίες για την υλοποίηση της κλάσης ή πολύπλοκων αλγορίθμων.
// Iterates over the contents of a GargantuanTable. Sample usage:
// GargantuanTableIterator* iter = table->NewIterator();
// for (iter->Seek("foo"); !iter->done(); iter->Next()) {
// process(iter->key(), iter->value());
// }
// delete iter;
class GargantuanTableIterator
{
...
private:
// Keeps track of the total number of entries in the table.
// Used to ensure we do not go over the limit. -1 means
// that we don't yet know how many entries the table has.
int num_total_entries_;
};
| 1 | Wikibooks, Computer Programming/Coding Style, |
| 2 | Linus Torvalds, Linux kernel coding style, |
| 3 | Sutter, Herb and Alexandrescu, Andrei, C++ coding standards: 101 rules, guidelines, and best practices, Pearson Education, 2004. |
| 4 | Wikipedia, Best coding practices --- {W}ikipedia{,} The Free Encyclopedia, |
| 5 | Google, Google C++ Style Guide, |