Η σωστή τεκμηρίωση κώδικα είναι μια σημαντική αλλά συχνά παραβλέπεται πτυχή της ανάπτυξης λογισμικού. Ως προγραμματιστής, θα έχετε συνηθίσει να γράφετε καθαρό, αποτελεσματικό κώδικα, αλλά μπορεί να είστε λιγότερο έμπειροι στη σύνταξη καλής τεκμηρίωσης.
Η καλή τεκμηρίωση είναι χρήσιμη για οποιονδήποτε εργάζεται με τον κώδικά σας, είτε πρόκειται για άλλα μέλη της ομάδας σας είτε για εσάς, τον εαυτό σας, σε μεταγενέστερη ημερομηνία. Μπορεί να εξηγήσει γιατί έχετε εφαρμόσει κάτι με συγκεκριμένο τρόπο ή πώς να χρησιμοποιήσετε μια συγκεκριμένη συνάρτηση ή API.
Για προγραμματιστές JavaScript, το JSDoc είναι ένας καλός τρόπος για να ξεκινήσετε την τεκμηρίωση του κώδικά σας.
Πίνακας περιεχομένων
Τι είναι το JSDoc;
Η τεκμηρίωση του κώδικα μπορεί να είναι περίπλοκη και κουραστική. Ωστόσο, περισσότεροι άνθρωποι αναγνωρίζουν τα οφέλη μιας προσέγγισης «έγγραφα ως κώδικας» και πολλές γλώσσες διαθέτουν βιβλιοθήκες που βοηθούν στην αυτοματοποίηση της διαδικασίας. Για απλή, σαφή και συνοπτική τεκμηρίωση. Ακριβώς όπως η γλώσσα Go έχει GoDoc για την αυτοματοποίηση της τεκμηρίωσης από κώδικα, έτσι και η JavaScript έχει JSDoc.
Το JSDoc δημιουργεί τεκμηρίωση ερμηνεύοντας ειδικά σχόλια στον πηγαίο κώδικα JavaScript, επεξεργάζοντας αυτά τα σχόλια και δημιουργώντας ειδική τεκμηρίωση. Στη συνέχεια καθιστά αυτή την τεκμηρίωση διαθέσιμη σε προσβάσιμη μορφή HTML.
Αυτό διατηρεί την τεκμηρίωση εντός του κώδικα, επομένως όταν ενημερώνετε τον κωδικό σας, είναι εύκολο να ενημερώσετε την τεκμηρίωση.
Ρύθμιση του JSDoc
Οι δημιουργοί του JSDoc έχουν κάνει εύκολο να ξεκινήσετε και να ρυθμίσετε το JSDoc στο έργο σας JavaScript.
Για να εγκαταστήσετε το JSDoc τοπικά, εκτελέστε:
npm install --save-dev jsdoc
Αυτό θα εγκαταστήσει τη βιβλιοθήκη στο έργο σας ως εξάρτηση dev.
Για να χρησιμοποιήσετε το JSDoc, θα χρησιμοποιήσετε ειδικά συντακτικά σχόλια μέσα στον πηγαίο κώδικα. Θα γράψετε όλα τα σχόλια τεκμηρίωσης μέσα στους δείκτες /** και */. Μέσα σε αυτά, μπορείτε να περιγράψετε καθορισμένες μεταβλητές, συναρτήσεις, παραμέτρους συναρτήσεων και πολλά άλλα.
Για παράδειγμα:
* Gets User by name.
* @param {string} name - The name of the User
* @returns {string} User
*/function getUser(name) {
const User = name;
return User;
}
Οι ετικέτες @param και @returns είναι δύο από τις πολλές ειδικές λέξεις-κλειδιά που υποστηρίζει το JSDoc για να εξηγήσει τον κώδικά σας.
Για να δημιουργήσετε την τεκμηρίωση για αυτόν τον κώδικα, εκτελέστε το npx jsdoc ακολουθούμενο από τη διαδρομή προς το αρχείο JavaScript.
Για παράδειγμα:
npx jsdoc src/main.js
Εάν εγκαταστήσατε το JSDoc καθολικά, μπορείτε να παραλείψετε τη σημαία npx και να εκτελέσετε:
Αυτή η εντολή θα δημιουργήσει έναν φάκελο out στη ρίζα του έργου σας. Μέσα στο φάκελο, θα βρείτε αρχεία HTML που αντιπροσωπεύουν τις σελίδες της τεκμηρίωσής σας.
Μπορείτε να προβάλετε την τεκμηρίωση ρυθμίζοντας έναν τοπικό διακομιστή ιστού για να τη φιλοξενήσει ή απλά ανοίγοντας το αρχείο out/index.html μέσα σε ένα πρόγραμμα περιήγησης. Ακολουθεί ένα παράδειγμα για το πώς θα μοιάζει μια σελίδα τεκμηρίωσης από προεπιλογή:
Διαμόρφωση της εξόδου JSDoc
Μπορείτε να δημιουργήσετε ένα αρχείο διαμόρφωσης για να αλλάξετε την προεπιλεγμένη συμπεριφορά του JSDoc.
Για να το κάνετε αυτό, δημιουργήστε ένα αρχείο conf.js και εξάγετε μια λειτουργική μονάδα JavaScript μέσα σε αυτό το αρχείο.
Για παράδειγμα:
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
Μέσα στο αρχείο ρυθμίσεων υπάρχουν διάφορα Διαμόρφωση JSDoc επιλογές. Η επιλογή προτύπου σάς επιτρέπει να χρησιμοποιήσετε ένα πρότυπο για να προσαρμόσετε την εμφάνιση της τεκμηρίωσης. Η κοινότητα του JSDoc παρέχει πολλά πρότυπα που μπορείτε να χρησιμοποιήσετε. Το πακέτο σας επιτρέπει επίσης να δημιουργήσετε τα δικά σας εξατομικευμένα πρότυπα.
Για να αλλάξετε τη θέση της τεκμηρίωσης που δημιουργείται, ορίστε την επιλογή διαμόρφωσης προορισμού σε έναν κατάλογο. Το παραπάνω παράδειγμα καθορίζει έναν φάκελο εγγράφων στη ρίζα του έργου.
Χρησιμοποιήστε αυτήν την εντολή για να εκτελέσετε το JSDoc με ένα αρχείο διαμόρφωσης:
jsdoc -c /path/to/conf.js
Για να διευκολύνετε την εκτέλεση αυτής της εντολής, προσθέστε την ως καταχώρηση σεναρίων στο αρχείο package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Τώρα μπορείτε να εκτελέσετε την εντολή δέσμης ενεργειών npm μέσα σε ένα τερματικό.
Ένα παράδειγμα τεκμηρίωσης που δημιουργήθηκε με το JSDoc
Παρακάτω είναι μια απλή αριθμητική βιβλιοθήκη με μεθόδους πρόσθεσης και αφαίρεσης.
Αυτό είναι ένα παράδειγμα καλά τεκμηριωμένου κώδικα JavaScript:
* A library for performing basic arithmetic operations.
* @module arithmetic
*/
module.exports = {
* Adds two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @return {number} The sum of the two numbers.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const sum = arithmetic.add(5, 10);
* console.log(sum);
*/
add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a + b;
},
* Subtracts the second number from the first number.
* @param {number} a - The number to subtract from.
* @param {number} b - The number to subtract.
* @return {number} The result of the subtraction.
* @throws {TypeError} If any of the arguments is not a number.
*
* @example
* const arithmetic = require('arithmetic');
* const difference = arithmetic.subtract(10, 5);
* console.log(difference);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a - b;
}
};
Τα σχόλια του JSDoc παρέχουν μια σαφή και περιεκτική περιγραφή της βιβλιοθήκης και των μεθόδων της, συμπεριλαμβανομένων:
- Περιγραφή της βιβλιοθήκης και του σκοπού της.
- Οι παράμετροι κάθε μεθόδου, συμπεριλαμβανομένου του τύπου τους και μια σύντομη περιγραφή.
- Η τιμή και ο τύπος που επιστρέφει κάθε μέθοδος.
- Τα λάθη που μπορεί να πετάξει κάθε μέθοδος και οι συνθήκες που το προκαλούν.
- Ένα παράδειγμα για το πώς να χρησιμοποιήσετε κάθε μέθοδο.
Τα σχόλια περιλαμβάνουν επίσης την ετικέτα @module για να υποδείξουν ότι αυτό το αρχείο είναι μια λειτουργική μονάδα και την ετικέτα @example για να παρέχει ένα παράδειγμα κώδικα για κάθε μέθοδο.
Τεκμηρίωση του κώδικα προγραμματιστή με τον σωστό τρόπο
Όπως μπορείτε να δείτε, το JSDoc είναι ένα πολύ χρήσιμο εργαλείο για να ξεκινήσετε την τεκμηρίωση κώδικα JavaScript. Με την εύκολη ενσωμάτωσή του, μπορείτε να δημιουργήσετε γρήγορη και λεπτομερή τεκμηρίωση καθώς γράφετε τον κώδικά σας. Μπορείτε επίσης να διατηρήσετε και να ενημερώσετε την τεκμηρίωση απευθείας στον χώρο εργασίας σας.
Ωστόσο, όσο χρήσιμη κι αν είναι η αυτοματοποίηση του JSDoc, θα πρέπει να τηρείτε ορισμένες οδηγίες, ώστε να μπορείτε να δημιουργήσετε ποιοτική τεκμηρίωση.