Hướng dẫn how do you write a good comment in javascript? - làm thế nào để bạn viết một bình luận tốt trong javascript?

Giới thiệu

Mục đích chính của việc viết mã là để một máy tính có thể giải thích nó như các lệnh. Tuy nhiên, điều quan trọng là mã chúng tôi viết cũng có thể dễ dàng giải thích bởi các nhà phát triển.

Bạn đã bao giờ quay lại một dự án và gặp khó khăn trong việc hiểu logic nội bộ? Đó có lẽ là vì cho biết dự án đã không được bình luận đúng.

Nhận xét là ghi chú được viết trong mã bị bỏ qua bởi công cụ JavaScript, điều đó có nghĩa là chúng không ảnh hưởng đến đầu ra theo bất kỳ cách nào. Mục đích duy nhất của họ mô tả cách thức và lý do tại sao mã hoạt động cho các nhà phát triển khác và chính bạn. are notes written in the code that are ignored by the JavaScript engine, which means they don't affect the output in any way. Their sole purpose describing how and why code works to other developers, and yourself.

Trong bài viết này, chúng tôi sẽ xem xét cách bình luận mã JavaScript, vì loại bình luận nào tồn tại và một số thực tiễn tốt nhất.

Nhận xét một dòng thường được sử dụng để nhận xét một phần của dòng hoặc dòng mã đầy đủ. Nhận xét một dòng trong JavaScript bắt đầu với //. Trình thông dịch sẽ bỏ qua mọi thứ ở bên phải của chuỗi điều khiển này cho đến khi kết thúc dòng.

Chúng ta hãy xem một ví dụ về một nhận xét duy nhất trong hành động:

// Print "Hello World" in the console
console.log("Hello World");

Ở đây, chúng tôi đang sử dụng một nhận xét một dòng để mô tả dòng mã tiếp theo đang làm gì. Nếu một nhận xét một dòng xuất hiện ở cuối dòng mã, thì nó được gọi là nhận xét nội tuyến.
If a single-line comment appears at the end of a line of code, it's called an inline comment.

Chúng thường được sử dụng để thêm các chú thích nhanh:

let c = a + b; // Assign sum of a, b to c

Nhận xét đa dòng và tài liệu JavaScript

Nếu chúng tôi muốn thêm một ghi chú được trải rộng trên nhiều dòng, chúng tôi có thể chọn nhận xét nhiều dòng hoặc nhận xét cấp khối.block-level comments.

Nhận xét đa dòng bắt đầu bằng

let c = a + b; // Assign sum of a, b to c
0 và kết thúc bằng
let c = a + b; // Assign sum of a, b to c
1:

/* The following program contains source code for a game called Tic-tac-toe.
It is a paper-and-pencil game for two players, X and O, who take turns marking the spaces in a 3×3 grid. 
The player who succeeds in placing three of their marks in a horizontal, vertical, or diagonal row is the winner
*/

Ở đây, một nhận xét đa dòng được sử dụng để mô tả tic-tac-toe. Nói chung, các nhận xét đa dòng được sử dụng để giới thiệu và giải thích một phần mã, trong đó một dòng/câu duy nhất không đủ.

Một loại nhận xét đa dòng khác cũng có thể được nhìn thấy cũng có thể được nhìn thấy:

/**
* The following program contains source code for a game called Tic-tac-toe.
* It is a paper-and-pencil game for two players, X and O, who take turns marking the
* spaces in a 3×3 grid. 
* The player who succeeds in placing three of their marks in a horizontal, vertical, or 
* diagonal row is the winner
*/

Thông thường, những bình luận này có thể bao gồm thông tin về mã tố tụng, chẳng hạn như các tham số của hàm hoặc thậm chí là tác giả của mã:

/**
* Function that greets a user
* @author   John
* @param    {String} name    Name of the user
* @return   {String}         Greeting message
*/
function greetUser(name) {
    return `Greetings, ${name}!`;
}

Những bình luận này được gọi là Docstrings, vì về cơ bản chúng là chuỗi (bình luận) tạo thành tài liệu về mã của bạn.

Những loại bình luận này thực sự hữu ích cho các nhà phát triển khác trong nhóm của bạn, vì bạn có thể làm rõ đầu vào mong đợi là gì, đầu ra là gì, cũng như liên hệ với ai nếu cần.

Một lợi ích bổ sung là bạn có thể tạo tài liệu dựa trên các tài liệu này.

Bên cạnh việc ghi chú, nhận xét cũng có thể được sử dụng để nhanh chóng ngăn chặn thực thi mã cho mục đích gỡ lỗi. Điều này là có thể bởi vì các công cụ JavaScript không diễn giải mã nhận xét. Điều này được gọi là bình luận ra mã.commenting out code.

Nếu có một dòng sai lầm, đó là gây ra vấn đề, chúng ta chỉ có thể "nhận xét nó" để vô hiệu hóa nó, mà không cần xóa dòng. Điều này có thể được kết hợp với những người gỡ lỗi thực tế để giúp bạn khẳng định những gì đang diễn ra.

Xem xét mã sau:

console.log("Working code");
console.log("Erroneous code);

Nếu chúng tôi muốn xóa câu lệnh thứ hai, nhưng không muốn xóa nó mãi mãi, chúng tôi có thể chỉ cần nhận xét nó:

console.log("Working code");
//console.log("Erroneous code);

Mẹo chuyên nghiệp: Trong hầu hết các trình chỉnh sửa mã, chúng ta có thể sử dụng phím tắt

let c = a + b; // Assign sum of a, b to c
2 cho Windows và
let c = a + b; // Assign sum of a, b to c
3 cho Mac để nhận xét một dòng mã duy nhất.
: In most of the code editors, we can use the keyboard shortcut
let c = a + b; // Assign sum of a, b to c
2 for Windows and
let c = a + b; // Assign sum of a, b to c
3 for Mac to comment out a single line of code.

Ngoài ra, bạn cũng có thể nhận xét toàn bộ phần nếu bạn không chắc bạn có xóa chúng hay không:

Kiểm tra hướng dẫn thực hành của chúng tôi, thực tế để học Git, với các thực hành tốt nhất, các tiêu chuẩn được công nghiệp chấp nhận và bao gồm bảng gian lận. Ngừng các lệnh git googling và thực sự tìm hiểu nó!

/*console.log("Entering for loop");
for (let i = 0; i < 100; i++) {
    console.log(i);
}*/

Trước hết, bình luận không phải là một cái cớ để viết mã không thể đọc được, và sau đó chỉ vá nó với năm đoạn bình luận giải thích nó. Trước tiên chúng ta phải tập trung vào việc viết mã sạch, tự giải thích, sau này có thể được cải thiện với các bình luận mang tính xây dựng.

Sử dụng ý kiến ​​để giải thích lý do tại sao bạn đã làm điều gì đó, chứ không phải cách bạn đã làm điều đó. Nếu bạn thấy mình giải thích cách bạn đã làm điều gì đó, thì đã đến lúc lùi lại một bước và tái cấu trúc mã của bạn thành một thứ gì đó tự giải thích.why you did something, not how you did it. If you find yourself explaining how you did something, then it's time to take a step back and refactor your code into something self-explanatory.

Một lời khuyên khác sẽ là không viết bình luận rõ ràng và là dự phòng theo bản chất. Ví dụ, nhận xét sau đây là hoàn toàn không cần thiết:

// Prints out the result
console.log(result)

Có các công cụ hữu ích, chẳng hạn như JSDOC 3 có thể tạo tài liệu, chỉ dựa trên các nhận xét trong mã của bạn, được định dạng như các tài liệu đã nêu ở trên.

Sự kết luận

Trong bài viết này, chúng tôi đã xem xét các bình luận là gì và làm thế nào để tạo ra chúng trong JavaScript. Chúng tôi đã xem xét các loại bình luận khác nhau-các bình luận một dòng và nhiều dòng, cũng như các tài liệu JavaScript đã đề cập.

Chúng tôi cũng đã thấy cách gỡ lỗi mã của chúng tôi bằng một kỹ thuật gọi là "bình luận", và cuối cùng đã tóm tắt một số thực tiễn nhận xét tốt.