Cách ghi lại mã JavaScript bằng JSDoc
Tài liệu mã phù hợp là một khía cạnh quan trọng nhưng thường bị bỏ qua trong quá trình phát triển phần mềm. Là một nhà phát triển, bạn sẽ quen với việc viết mã rõ ràng, hiệu quả nhưng bạn có thể ít kinh nghiệm hơn trong việc viết tài liệu hay.
Tài liệu tốt sẽ hữu ích cho bất kỳ ai làm việc với mã của bạn, cho dù đó là các thành viên khác trong nhóm của bạn hay chính bạn sau này. Nó có thể giải thích lý do tại sao bạn triển khai điều gì đó theo một cách cụ thể hoặc cách sử dụng một chức năng hoặc API cụ thể.
Đối với các nhà phát triển JavaScript, JSDoc là một cách hay để bắt đầu ghi lại mã của bạn.
Mục lục
JSDoc là gì?
Mã tài liệu có thể phức tạp và tẻ nhạt. Tuy nhiên, ngày càng có nhiều người nhận ra lợi ích của cách tiếp cận “tài liệu dưới dạng mã” và nhiều ngôn ngữ có thư viện giúp tự động hóa quy trình. Đối với tài liệu đơn giản, rõ ràng và ngắn gọn. Giống như ngôn ngữ Go có GoDoc để tự động hóa tài liệu từ mã, JavaScript cũng có JSDoc.
JSDoc tạo tài liệu bằng cách diễn giải các nhận xét đặc biệt trong mã nguồn JavaScript của bạn, xử lý các nhận xét này và tạo tài liệu riêng. Sau đó, nó cung cấp tài liệu này ở định dạng HTML có thể truy cập được.
Điều này giữ tài liệu nằm trong mã, vì vậy khi bạn cập nhật mã, bạn có thể dễ dàng cập nhật tài liệu.
Thiết lập JSDoc
Những người tạo ra JSDoc đã giúp bạn dễ dàng bắt đầu và thiết lập JSDoc trong dự án JavaScript của mình.
Để cài đặt JSDoc cục bộ, hãy chạy:
npm install --save-dev jsdoc
Điều này sẽ cài đặt thư viện trong dự án của bạn dưới dạng phụ thuộc vào nhà phát triển.
Để sử dụng JSDoc, bạn sẽ sử dụng các chú thích cú pháp đặc biệt bên trong mã nguồn của mình. Bạn sẽ viết tất cả các nhận xét tài liệu của mình trong các dấu /** và */. Bên trong chúng, bạn có thể mô tả các biến, hàm, tham số hàm được xác định và nhiều thứ khác.
Ví dụ:
* Gets User by name.
* @param {string} name - The name of the User
* @returns {string} User
*/function getUser(name) {
const User = name;
return User;
}
Thẻ @param và @returns là hai trong số nhiều từ khóa đặc biệt mà JSDoc hỗ trợ để giải thích mã của bạn.
Để tạo tài liệu cho mã này, hãy chạy npx jsdoc theo sau là đường dẫn đến tệp JavaScript của bạn.
Ví dụ:
npx jsdoc src/main.js
Nếu bạn đã cài đặt JSDoc trên toàn cầu, bạn có thể bỏ qua cờ npx và chạy:
Lệnh này sẽ tạo một thư mục out trong thư mục gốc của dự án của bạn. Bên trong thư mục, bạn sẽ tìm thấy các tệp HTML đại diện cho các trang tài liệu của bạn.
Bạn có thể xem tài liệu bằng cách thiết lập một máy chủ web cục bộ để lưu trữ nó hoặc đơn giản bằng cách mở tệp out/index.html bên trong trình duyệt. Dưới đây là ví dụ về trang tài liệu sẽ trông như thế nào theo mặc định:
Định cấu hình đầu ra JSDoc
Bạn có thể tạo tệp cấu hình để thay đổi hành vi mặc định của JSDoc.
Để làm như vậy, hãy tạo tệp conf.js và xuất mô-đun JavaScript bên trong tệp này.
Ví dụ:
module.exports = {
source: {
includePattern: ".+\\\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
Bên trong file cấu hình rất đa dạng Cấu hình JSDoc tùy chọn. Tùy chọn mẫu cho phép bạn sử dụng mẫu để tùy chỉnh giao diện của tài liệu. Cộng đồng JSDoc cung cấp nhiều mẫu mà bạn có thể sử dụng. Gói này cũng cho phép bạn tạo các mẫu được cá nhân hóa của riêng bạn.
Để thay đổi vị trí của tài liệu đã tạo, hãy đặt tùy chọn cấu hình đích thành một thư mục. Ví dụ trên chỉ định thư mục tài liệu trong thư mục gốc của dự án.
Sử dụng lệnh này để chạy JSDoc với tệp cấu hình:
jsdoc -c /path/to/conf.js
Để giúp chạy lệnh này dễ dàng hơn, hãy thêm nó dưới dạng mục nhập tập lệnh bên trong tệp pack.json của bạn:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Bây giờ bạn có thể chạy lệnh npm script bên trong terminal.
Một ví dụ về tài liệu được tạo bằng JSDoc
Dưới đây là một thư viện số học đơn giản với các phương thức cộng và trừ.
Đây là một ví dụ về mã JavaScript được ghi chép đầy đủ:
* 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;
}
};
Các nhận xét của JSDoc cung cấp mô tả rõ ràng và toàn diện về thư viện cũng như các phương pháp của nó, bao gồm:
- Mô tả về thư viện và mục đích của nó.
- Các tham số của mỗi phương thức, bao gồm loại của chúng và mô tả ngắn gọn.
- Giá trị và kiểu mà mỗi phương thức trả về.
- Các lỗi mà mỗi phương pháp có thể mắc phải và các điều kiện gây ra lỗi đó.
- Một ví dụ về cách sử dụng từng phương pháp.
Các nhận xét cũng bao gồm thẻ @module để cho biết rằng tệp này là một mô-đun và thẻ @example để cung cấp mã ví dụ cho từng phương thức.
Ghi lại mã nhà phát triển đúng cách
Như bạn có thể thấy, JSDoc là một công cụ rất hữu ích giúp bạn bắt đầu ghi lại mã JavaScript. Với khả năng tích hợp dễ dàng, bạn có thể tạo tài liệu nhanh chóng và chi tiết khi viết mã. Bạn cũng có thể duy trì và cập nhật tài liệu ngay trong không gian làm việc của mình.
Tuy nhiên, dù tính năng tự động hóa của JSDoc rất hữu ích nhưng bạn vẫn nên tuân thủ một số nguyên tắc nhất định để có thể tạo tài liệu chất lượng.
