Σχολιασμός και τεκμηρίωση (αγγλ. Commenting and Documentantion) ([1])
Η τεκμηρίωση και ο σχολιασμός του πηγαίου κώδικα είναι μία από τις πιο σημαντικές διαδικασίες κατά την παραγωγή του. Αν και δεν συνδέεται άμεσα με την λειτουργικότητα του κώδικα, συνδέεται έμμεσα με την δυνατότητα επέκτασης του, μιας και παρέχει με διορατικό τρόπο τις προθέσεις του αρχικού προγραμματιστή.
Κατάλληλα θέματα για την τεκμηρίωση συχνά περιλαμβάνουν:
- Γενική περιγραφή του προγράμματος. Πρέπει να περιλαμβάνει:
- Μία επισκόπηση για το τον σκοπό που δημιουργήθηκε το πρόγραμμα.
- Ένα απλό παράδειγμα χρήσης του προγράμματος.
- Οδηγίες εκμάθησης για την βασική χρήση του προγράμματος.
- Τεκμηρίωση του κώδικα. Η τεκμηρίωση του κώδικα περιλαμβάνει:
- Περιγραφή των κλάσεων και των συναρτήσεων του προγράμματος.
- Την σχέση μεταξύ των κλάσεων και των συναρτήσεων.
- Για κάθε συνάρτηση, ανάλογα με την περίπτωση, μία περιγραφή, τις απαιτήσεις για την σωστή λειτουργία της, τα αποτελέσματα της, την τιμή που επιστρέφει καθώς και τυχόν σφάλματα που μπορεί να συμβούν.
- Εντοπισμό σφαλμάτων και στρατηγικές για την αποφυγή τους.
- Πως μεταγλωττίζεται και συνδέεται το πρόγραμμα.
- Η εκδοσή του προγράμματος και τυχόν αλλαγές που έχουν συμβεί.
- Αιτιολόγηση για τη λήψη αποφάσεων σχεδιασμού.
- Τυχόν ευχαριστίες.
Με τα σχόλια και την τεκμηρίωση διασφαλίζεται ότι ο κώδικας έχει περιγραφτεί με επαρκείς λεπτομέρειες έτσι ώστε όταν κάποιος κοιτάζει τον πηγαίο κώδικα θα μπορεί εύκολα να καταλάβει το σχεδιασμό και το σκοπό του κώδικα ([1]).
Γενικά σχόλια ([2],[3],[4],[5])
- Σε γενικές γραμμές, χρειάζεται τα σχόλια να λένε ΤΙ κάνουν στον κώδικα και όχι ΠΩΣ το κάνουν.
- Τα καλύτερα σχόλια στον πηγαίο κώδικα είναι ο ίδιος ο πηγαίος κώδικας. Γι` αυτό το λόγο ο κώδικας θα πρέπει να "αυτο-τεκμηριώνεται". Είναι προτιμητέο να εξηγείτε κάτι μέσα από τον ίδιο τον πηγαίο κώδικα (π.χ. με την χρήση κάποιου πολύπλοκου ονόματος μεταβλητής) παρά να χρησιμοποιούνται αργότερα σχόλια τα οποία εξηγούν τί κάνει ο συγκεκριμένος κώδικας.
- Σχόλια πρέπει να τοποθετούνται:
- σε πολύπλοκα,
- μη προφανή,
- ενδιαφέροντα ή
- σημαντικά σημεία του πηγαίου κώδικα.
Πριν από αυτά τα σημεία θα πρέπει να τοποθετούνται μικρά σχόλια τα οποία επεξηγούν τί κάνει ο κώδικας. Παραδείγματος χάρη:
// 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;
}
- Αν τα σχόλια εκτείνονται σε αρκετές γραμμές, μπορεί η στοίχιση τους να τα κάνει πιο ευανάγνωστα. Παραδείγματος χάρη:
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. */
Σχόλια οντοτήτων
Η παρακάτω ενότητα αναφέρει μερικούς από τους πιο διαδεδομένους τρόπους που χρησιμοποιούνται για να σχολιάσουν τις οντότητες του πηγαίου κώδικα.
Αρχεία
- Κάθε αρχείο πρέπει να περιέχει την άδεια χρήσης του πηγαίου κώδικα (π.χ. Apache 2.0, BSD, LGPL, GPL). Η επιλογή της κατάλληλης άδειας χρήσης είναι πολύπλοκη διαδικασία η οποία όμως δεν πρέπει να αμελείται.
- Πρέπει να περιέχεται ο συγγραφέας του πηγαίου.
- Κάθε αρχείο πρέπει να έχει ένα σχόλιο το οποίο περιγράφει τα περιεχόμενα του.
/*
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 ...
*/
Μεταβλητές
- Σε γενικές γραμμές το όνομα μίας μεταβλητής θα πρέπει να είναι αρκετά περιγραφικό ώστε να δίνει την δυνατότητα στον προγραμματιστή να καταλάβει για ποιο λόγο χρησιμοποιείται η συγκεκριμένη μεταβλητή. Σε ορισμένες περιπτώσεις, μερικά παραπάνω σχόλια χρειάζονται.
// The total number of tests cases that we run through
// in this regression test.
const int k_num_test_cases = 6;
Συναρτήσεις(1)
- Κάθε δήλωση συνάρτησης θα πρέπει να έχει σχόλια τα οποία προηγούνται της συνάρτησης και περιγράφουν τί κάνει η συνάρτηση και πως να χρησιμοποιείται. Γενικά τα σχόλια στην δήλωση μίας συνάρτησης περιγράφουν την χρήση της συνάρτησης, ενώ τα σχόλια στην υλοποίηση μίας συνάρτησης περιγράφουν την λειτουργίας της.
- Κατά την δήλωση μίας συνάρτησης πρέπει να αναφέρονται:
- Οι μεταβλητές εισόδου και οι μεταβλητές που επιστρέφει η συνάρτηση.
- Εάν η συνάρτηση δεσμεύει μνήμη την οποία ο προγραμματιστής θα πρέπει να την αποδεσμεύσει (αυτό ισχύει σε γλώσσες που δεν έχουν συλλογή απορριμάτων (αγγλ. garbage collection) όπως η 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, |