Documentation & Unit testing framework για C

[gon1332]

Καλημέρα σας,

 

όσον αφορά εργαλείο για documentation έχω στα top το doxygen. Αν και προσωπικά δεν το

έχω χρησιμοποιήσει έχω δει μεγάλα και σοβαρά projects να κάνουν χρήση του. Επίσης μέλη

του insomnia το χρησιμοποιούν και γενικά το βλέπω top στα προτεινόμενα. Λέω να ξεκινήσω

κι εγώ να το χρησιμοποιώ ώστε να ξεφύγω από το doxumentation που περιορίζεται στα σχό-

λια στον κώδικά μου. Επίσης, το γεγονός ότι πρέπει να ακολουθήσω κάποια πρότυπα θα με

αναγκάσουν να είμαι πάντα συνεπής και να γράφω όσο το δυνατόν καλύτερο documentation.

 

Αφήνοντας την εισαγωγή, προσπάθησα να χρησιμοποιήσω για πρώτη φορά το doxygen σε

κώδικα που περιέχει 3 header files και 4 C source files. To documentation βρίσκεται στα hea-

der files. Τα βήματα που ακολούθησα είναι τα εξής:

 

1] Εγκατέστησα την τελευταία έκδοση του doxygen από source.

2] Έφτιαξα ένα configuration file στο directory του κώδικα.

3] Άλλαξα το configuration file (ελπίζω στα μέτρα μου).

4] Προσπάθησα να δημιουργήσω το documentation του κώδικα.

 

Το πρόβλημα είναι ότι μου βγάζει documentation μόνο από ένα struct σε C source file. Τίποτα

από τα header files. Δοκίμασα έτσι να γράψω documentation στα source files. Τίποτα. Μόνο το

struct φαινόταν. Να διευκρινήσω πως με κάθε αλλαγή διέγραφα το παλιό doc και το δημιουργού-

σα από την αρχή. Ορίστε και ο κώδικας που προσπαθώ να το εφαρμόσω. Μέσα μπορεί να βρει

κανείς και το configuration file. Για να δημιουργήσει το documentation αρκεί να γράψει make docs.

Κάτι άλλο παράξενο που παρατήρησα είναι πως δεν τρέχει το preprocessor κάτι είναι ενεργο-

ποιημένο στο configuration.

 

 

Ένα άλλο θέμα που θα ήθελα να ξεκινήσω είναι η επιλογή ενός εργαλείου για Unit Testing σε C.

Προσωπικά δε χρησιμοποιώ κάποιο framework, αλλά περιορίζομαι σε μικρές δικές μου λύσεις.

Βέβαια για μεγάλα projects θα είναι απαραίτητο κάποιο framework. Ή όχι; Γιατί ας πούμε αυτά

αντί για αυτό; Επίσης έχω δει ότι στη Nokia κάνουν χρήση του Robot. Τι έχετε να πείτε από τη

μέχρι τώρα εμπειρία σας;

[imitheos]

όσον αφορά εργαλείο για documentation έχω στα top το doxygen. Αν και προσωπικά δεν το

έχω χρησιμοποιήσει έχω δει μεγάλα και σοβαρά projects να κάνουν χρήση του. Επίσης μέλη

του insomnia το χρησιμοποιούν και γενικά το βλέπω top στα προτεινόμενα. Λέω να ξεκινήσω

κι εγώ να το χρησιμοποιώ ώστε να ξεφύγω από το doxumentation που περιορίζεται στα σχό-

λια στον κώδικά μου. Επίσης, το γεγονός ότι πρέπει να ακολουθήσω κάποια πρότυπα θα με

αναγκάσουν να είμαι πάντα συνεπής και να γράφω όσο το δυνατόν καλύτερο documentation.

Το doxygen όντως είναι πολύ καλό αλλά θα δεις πολλούς να το θεωρούν κακή πρακτική. Σε αυτό δεν φταίει φυσικά το doxygen αλλά η πρακτική μερικών προγραμματιστών να γράφουν "κακό" κώδικα και να γράφουν κατεβατά στο doxygen για να τον περιγράψουν.

 

Γράψε ωραίες μικρές συναρτήσεις που να κάνουν ένα μόνο πράγμα και να το κάνουν ξεκάθαρα ("the unix way" που λέγανε παλιά στα χωριά) και έπειτα χρειάζεται πολύ λίγα σχόλια για την περιγραφή. Επίσης ακόμη ένα στάδιο documentation είναι τα VCS commit messages. Δεν διαβάζονται από τόσο κόσμο και τόσο συχνά όσο η τεκμηρίωση (manpages, doxygen, whatever) και όσο τα σχόλια στον κώδικα αλλά είναι πολύ σημαντικά και σε σώζουν σε περιπτώσεις git-bisect, git-blame, κτλ. Εδώ για παράδειγμα έχεις τίτλο "Hide the pointer of the struct from the user" χωρίς να αναφέρεις τίποτα γιατί το έκανες. Στην παρούσα περίπτωση φυσικά είναι προφανές αλλά το αναφέρω ως παράδειγμα.

 

Επίσης λόγω της μεγάλης ταχύτητας με την οποία γίνονται οι εργασίες στα DVCS, είναι καλή πρακτική να έχεις ξεκάθαρα commits που να κάνουν ένα πράγμα. Στο συγκεκριμένο commit εκτός από την αλλαγή των δεικτών έχεις και μια αλλαγή των σχολίων του doxygen από @brief σε \brief που αφενός είναι άσχετη με τους δείκτες και αφετέρου δεν αναφέρεται πουθενά στο commit message.

 

Όλα τα παραπάνω φυσικά είναι offtopic από αυτό που ρωτάς απλά τα έγραψα σαν γενική συμβουλή.

 

Το πρόβλημα είναι ότι μου βγάζει documentation μόνο από ένα struct σε C source file. Τίποτα

από τα header files. Δοκίμασα έτσι να γράψω documentation στα source files. Τίποτα. Μόνο το

struct φαινόταν. Να διευκρινήσω πως με κάθε αλλαγή διέγραφα το παλιό doc και το δημιουργού-

σα από την αρχή. Ορίστε και ο κώδικας που προσπαθώ να το εφαρμόσω. Μέσα μπορεί να βρει κανείς και το configuration file. Για να δημιουργήσει το documentation αρκεί να γράψει make docs. Κάτι άλλο παράξενο που παρατήρησα είναι πως δεν τρέχει το preprocessor κάτι είναι ενεργο-

ποιημένο στο configuration.

Το doxygen από τη μάνα του έχει απενεργοποιημένη την επιλογή extract_all και έτσι δεν δημιουργεί τεκμηρίωση για τα πάντα αλλά μόνο για ό,τι του πεις εσύ. Αυτό έχει δύο θετικά. Το ένα είναι ότι δεν "μολύνεται" η τεκμηρίωση με άχρηστες πληροφορίες.

Δες την παρακάνω εικόνα για παράδειγμα. Αυτή είναι η τεκμηρίωση του αρχείου σου test_suite.h με ενεργοποιημένη την επιλογή extract_all. Επειδή δεν έχεις γράψει κάποιο σχόλιο, το doxygen δεν ξέρει τι μπορεί να ήθελες να πετύχεις γράφοντας τον συγκεκριμένο κώδικα οπότε απλά γράφει τι συναρτήσεις και μεταβλητές έχει το αρχείο. Αυτό όμως δεν προσφέρει τίποτα γιατί θα μπορούσαμε να πάρουμε την ίδια πληροφορία διαβάζοντας τον κώδικα.

 

Το δεύτερο θετικό είναι ότι επειδή δεν έχεις πει στο doxygen να τεκμηριώσει τα πάντα, του επιτρέπεις να σε ενημερώσει αν ξεχάσεις να τεκμηριώσεις κάτι και να σου πει όπα ψηλέ στο τάδε αρχείο έχεις τεκμηρίωση για την coo_new αλλά όχι για την coo_delete.

 

Τώρα θα μου πεις γιατί τα έγραψα όλα αυτά και τι σχέση έχουν με την ερώτησή σου. Αν ενεργοποιήσεις την επιλογή extract_all θα δεις ότι θα υπάρχουν όλα τα σχόλια που έχεις γράψει και στα .h και στα .c. Υπάρχει όμως και ένας άλλος τρόπος (κατ' εμέ καλύτερος) να κάνεις αυτό που θέλεις.

 

Όπως βλέπεις στην παραπάνω εικόνα, δεν μπορείς να κάνεις κλικ σε κανένα αρχείο γιατί το doxygen δεν έχει τεκμηριώσει κανένα από τα δύο, άσχετα αν εσύ είχες γράψει σχόλια.

% git diff                          [master U]
diff --git a/coo_sparse.h b/coo_sparse.h
--- a/coo_sparse.h
+++ b/coo_sparse.h
@@ -2,6 +2,11 @@
 #define COO_SPARSE_H_7EUNGWRE
 #include <stdlib.h> // for size_t
 
+/**
+ * @file coo_sparse.h
+ * @brief Function prototypes for COO
+ */
+

Αν προσθέσουμε τον παραπάνω κώδικα (θα μπορούσαμε να δηλώσουμε ότι είναι μέλος κάποιου module και χίλιες δύο άλλες πληροφορίες αλλά έβαλα την ελάχιστη πληροφορία που χρειάζεται) λέμε στο doxygen ότι αυτό το αρχείο περιέχει την τάδε πληροφορία. Έπειτα βλέπουμε στην παρακάτω εικόνα ότι μπορούμε να κάνουμε κλικ.

Αν κάνουμε κλικ παίρνουμε κανονικά όλη την τεκμηρίωση που έχεις γράψει.

 

Ένα άλλο θέμα που θα ήθελα να ξεκινήσω είναι η επιλογή ενός εργαλείου για Unit Testing σε C.

Προσωπικά δε χρησιμοποιώ κάποιο framework, αλλά περιορίζομαι σε μικρές δικές μου λύσεις.

Βέβαια για μεγάλα projects θα είναι απαραίτητο κάποιο framework. Ή όχι; Γιατί ας πούμε αυτά

αντί για αυτό; Επίσης έχω δει ότι στη Nokia κάνουν χρήση του Robot. Τι έχετε να πείτε από τη

μέχρι τώρα εμπειρία σας;

Συνήθως μεγάλα project (πχ git) έχουν κάποια δική τους υλοποίηση. Για μικρά project υπάρχουν διάφορα που μπορείς να τρέξεις όπως δείχνει και το νήμα του SO που έδωσες. Από το νήμα εγώ έχω δουλέψει τα minunit, cunit, cutest και επίσης τα Unity, CU. Δεν μπορώ να πω ότι το Χ είναι το καλύτερο μια και όλα είχαν κάποιο ωραίο feature που έλειπε από τα υπόλοιπα αλλά σε αυτό που κατέληξα (ίσως γιατί ήταν το πρώτο που δούλεψα και μου αρκούσε για αυτά που ήθελα) ήταν το cunit. Θα πρέπει να τα δοκιμάσεις και να δεις ποιο θα σου κάνει αυτό που θέλεις.

[gon1332]

Ευχαριστώ πάρα πολύ για τις παρατηρήσεις σου. Εννοείται

πως θα τις λάβω υπόψη μου. Και με το doxygen με αυτά

που μου είπες θα αρχίσω να πειραματίζομαι περισσότερο.

 

Όσον αφορά το unit testing, κι εγώ γενικά, όσο το έψαξα δε

βρήκα τη χρυσή τομή. Αυτό που είπες ακριβώς. Το καθένα

έχει τα features του που το άλλο δεν έχει. Θα αρχίσω να

χρησιμοποιώ κάποιο από αυτά που ανέφερες και θα επα-

νέλθω.

[imitheos]

Ευχαριστώ πάρα πολύ για τις παρατηρήσεις σου. Εννοείται

πως θα τις λάβω υπόψη μου. Και με το doxygen με αυτά

που μου είπες θα αρχίσω να πειραματίζομαι περισσότερο.

Έχει πάρα πολλά πράγματα για να παίξεις και μπορείς να φέρεις το αποτέλεσμα στα μέτρα που θέλεις.

 

Όσον αφορά αυτό που είπες πριν ότι δοκίμασες να γράψεις σχόλια στο .c, εγώ ένα πράγμα που κάνω είναι να χωρίζω την τεκμηρίωση ώστε στο κάθε σημείο να είναι μόνο η τεκμηρίωση που πρέπει (αν και οι απόψεις διίστανται πάνω στο κατά πόσο είναι καλή πρακτική γιατί ακριβώς χωρίζει η τεκμηρίωση και έχεις πληροφορία διασκορπισμένη σε πολλά σημεία).

 

coo_sparse.h

/*! \brief Creates a matrix in a triplet form according to COO scheme.
 *
 * \param nz Number of non-zero elements
 * \return Pointer to the triplet form
 *
 * Usage:
 * \code
 *     coo_matrix_T cm;
 *     cm = coomatrix_new(50, 3);
 * \endcode
 * ========================================================================= */
extern T coo_matrix_new(size_t orig_size, size_t nz);

coo_sparse.c

/**
 * \details
 * Creates a new matrix by allocating memory and
 * initializing values of the structure fields.
 *
 * After testing the X, Y, Z algorithms, the X algorithm was
 * chosen because it had great performance and small memory
 * footprint.
 *
 * \todo Modify the "bytes" calculation to avert possible overflow
 * (maybe use calloc)
 *
 * \bug zarro boogs here
 */
T coo_matrix_new(size_t orig_size, size_t nz)

Με αυτό τον τρόπο, στο header έχεις τι κάνει η συνάρτηση, τι μεταβλητές χρειάζεται, τι θεωρούμε δεδομένο (με το \pre μπορείς να δηλώσεις preconditions), παράδειγμα χρήσης, κτλ δηλαδή την περιγραφή του API ώστε να ξέρει ο χρήστης τι να περιμένει από τη βιβλιοθήκη σου. Στο c αρχείο έχεις λεπτομέρειες που αφορούν την υλοποίηση και χρειάζεται να ξέρει μόνο αυτός που θα πάει να αναπτύξει τον κώδικα.

 

Το doxygen φροντίζει να ενώσει πολλαπλές δηλώσεις που αφορούν το ίδιο αντικείμενο σε μία και έτσι παίρνουμε το παρακάτω αποτέλεσμα.

[gon1332]

Ωραία! Το παράδειγμα που παρουσίασες είναι όπως ακριβώς

θα ήθελα να είναι το documentation σε αρκετά γνωστά projects.

Όντως μπορείς να κάνεις αρκετά πράγματα. Αρχίζει και μου

αρέσει όλο και πιο πολύ..σπάει η μονοτονία. Βρήκα και τρόπο

να ενσωματώσω κομματάκια και κομματάκια latex. Βέβαια πρέπει

να κρατιέται κι ένα μέτρο και κυρίως ενήμερο με βάση τις τελευ-

ταίες αλλαγές στον κώδικα.

 

Υποστηρίζει και markdown οπότε είναι πραγματικά πολυεργαλείο.

Είδα παράγει και UML. Μέχρι δένδρα εξαρτήσεων είχα δει στον\

documentation του LLVM.

[brute-force]

Είχα κάτσει στην πτυχιακή μου να βρω ένα testing framework για να τεστάρω κομμάτια κώδικα αλλά τελικά κατέληξα σε builtin testing που έφτιαξα ως ξεχωριστό library. Γενικά η φάση με τη C (testing, profiling, κλπ.) έχει μείνει λίγο 80s. Αν θέλεις να ασχοληθείς με όλα τα στάδια της ανάπτυξης λογισμικού άκοπα τότε θα σου πρότεινα να ασχοληθείς με Go. Παρόμοια σύνταξη με C plus πακέτο με τη γλώσσα πάνε testing, profiling, παραγωγή documentation, και πολλά άλλα.