Có phong cách bình luận ảnh hưởng đến cách người đọc hiểu mã?


8

Câu hỏi này đã ám ảnh tôi trong 2 tháng qua.

Cách đây một thời gian, một người bạn là một lập trình viên tuyệt vời đã đưa cho tôi một số mã ví dụ và lần đầu tiên tôi nhận thấy một phong cách tổ chức bình luận độc đáo. Anh ấy đã nỗ lực để thiết kế các bình luận theo cách giúp tôi thoải mái hơn với chính mã. Ví dụ:

/////////////////////////////////////////////                                                   //                                             //
//  This code prints a basic "Hello world" //
// message to the console screen. You can  //
// change the text in the brackets.        //
//                                         //
/////////////////////////////////////////////

#include <iostream>

int main() {
  cout << "Hello world";

}

khi anh ta có thể viết đơn giản

/* This code prints a basic "Hello world" message to the console, change text in brackets */

 #include <iostream>

int main() {
  cout << "Hello world";

}

Loại ví dụ này chỉ ở quy mô lớn hơn. Tôi thấy điều này hơi không hiệu quả trong các tình huống chuyên nghiệp nhưng trong một tình huống học tập, nó có vẻ lý tưởng.

Câu hỏi ở đây là, nếu phong cách bình luận ảnh hưởng đến cách người đọc hiểu mã. Theo ý kiến ​​cá nhân của tôi, tùy chọn số 1 đẹp hơn mắt và dễ theo dõi hơn số 2. Có phải cách bạn nhận xét về mã ảnh hưởng đến khả năng hiểu mã của bạn, hay nó chỉ lãng phí thời gian và không gian?


Cả hai ví dụ của bạn là những ví dụ tốt về phong cách nhận xét kém cho mã chuyên nghiệp. Hộp bình luận không nên được sử dụng, và cũng nên tránh bình luận chặn. Các nhà giáo dục dường như thích hộp bình luận mặc dù.
Ryathal

Câu trả lời:


5

Đúng

Bố cục của một chương trình từ góc độ khoảng trắng và nhận xét sẽ có tác động lớn đến mức độ nhà phát triển có thể đọc mã của bạn.

Prettier to the eye and more easy to follow là chủ quan và sẽ không giống nhau cho mọi lập trình viên.

Điều đó đang được nói, một số nhà phát triển thích xem nhiều mã hơn trên màn hình cùng một lúc, trong khi những người khác thích có nhiều khoảng trắng / bình luận hơn.

Vào cuối ngày, bạn sẽ thoải mái hơn khi đọc mã mà bạn đã quen đọc.

Chú Bob Martin, tác giả của Clean Code đưa ra lập luận rằng các bình luận thường được sử dụng để bào chữa cho mã xấu và nên tránh bất cứ khi nào có thể. Thay vào đó, mã của bạn phải dễ đọc và được tổ chức đủ tốt để cho phép nhà phát triển khác dễ dàng lấy nó và bắt đầu làm việc.


"Dễ theo dõi hơn" thực sự là một trong những điều dễ dàng hơn để đo lường và định lượng. Ví dụ, bạn có thể trình bày các nhóm lập trình viên có năng lực ngẫu nhiên với một mẫu mã có lỗi và mất bao lâu để họ tìm thấy nó (trước tiên bạn cần thiết lập đường cơ sở, trình bày cả hai nhóm với một loạt mã giống hệt nhau các mẫu; điều này thậm chí còn quan trọng hơn nếu các nhóm của bạn nhỏ hoặc phương pháp ngẫu nhiên của bạn có thể không tối ưu). Các tác vụ khác có thể bao gồm dự đoán đầu vào, xác định độ phức tạp thuật toán hoặc đoán mã làm gì (kiểu nhiều lựa chọn).
tdammers

1
"Bình luận thường được sử dụng để bào chữa cho mã xấu và nên tránh bất cứ khi nào có thể" nghe có vẻ như rác rưởi đối với tôi. Những gì anh ấy nên nói là "mã xấu nên tránh bất cứ khi nào có thể".
Sardathrion - chống lại lạm dụng SE

1
@Sardathrion Ông không nói để tránh mã xấu. Trong thực tế, toàn bộ cuốn sách của ông là về cách tránh viết mã xấu. Ông cũng nói để tránh thực hành phổ biến là dùng đến các bình luận để che giấu mã xấu khi bạn có thể viết mã tốt hơn.
Eric King

@EricKing: Tôi chưa đọc cuốn sách nên không thể bình luận về những gì tác giả thực sự nói. Tuy nhiên, tóm tắt của Robert Greiner có nội dung như " Nhận xét được sử dụng để che giấu mã xấu, do đó, nên tránh nhận xét ". Tôi tin rằng đây là rác hoàn toàn bất cứ ai nói nó. Sử dụng bình luận để che dấu mã xấu là thực hành xấu. Không bình luận mã của bạn là thực hành xấu. Mã tốt và ý kiến ​​tốt là thực hành tốt. ;> Robert Greiner: bạn có thể nói rõ ý của bạn không?
Sardathrion - chống lại lạm dụng SE

1
@Sardathrion bạn đã trích dẫn sai cho tôi. Tôi đã từng nghĩ giống như bạn khi tôi mới bắt đầu lập trình và sự thật là, những bình luận đó không phải là tất cả những gì họ bị bẻ khóa. Tôi khuyên bạn nên kiểm tra Clean Code nếu bạn muốn tìm hiểu thêm về cách viết mã tuyệt vời. Nó thực sự giúp định hình cách tôi nghĩ về lập trình và tôi nghĩ nó sẽ giúp bất cứ ai đọc nó trở thành một lập trình viên tốt hơn.
Robert Greiner

7

Tôi tin rằng định dạng mã có thể tạo ra sự khác biệt lớn về khả năng đọc, nhưng chủ yếu là mã được định dạng tốt (hoặc thậm chí chỉ được thụt lề) mang lại cho tôi cảm giác ấm áp, mờ nhạt mà người viết thực sự quan tâm, thay vì chỉ cắt - dán bất cứ đoạn nào anh ấy hoặc cô ấy có trong tay.

Tôi không chắc lắm về ý kiến. Mã mà tôi viết, tôi tin chắc rằng các bình luận giúp. Mặt khác, nếu tôi muốn hiểu mã "doanh nghiệp" mà tôi gặp trong công việc, tôi thường xóa tất cả các bình luận, định dạng lại mã để thụt lề nhất quán và in ra giấy để đọc chi tiết, đánh dấu các khối cơ bản với bút chì, vv

Sự mâu thuẫn này (tôi: bình luận tốt; mọi người khác: bình luận sai lệch) khiến tôi nghĩ rằng những bình luận được đánh giá quá cao. Ngay cả của riêng tôi.


1
Điều này xứng đáng +1 chỉ cho đoạn cuối cùng :-)
Jörg W Mittag

Tôi đã từng muốn lập trình viên cuối cùng của chúng tôi sử dụng ý kiến. Sau đó, tôi tìm thấy một phần mã của anh ấy để lại bình luận. Bây giờ tôi ước lập trình viên cuối cùng của chúng tôi không sử dụng bình luận.
Ben Brocka

6

Vâng, phong cách bình luận ảnh hưởng đến khả năng đọc (làm sao có thể không?), Nhưng tôi sẽ cho rằng ví dụ bạn đưa ra là một phong cách rất kém. Định dạng quá mức chỉ là: quá mức.

Viết bình luận tốt là một kỹ năng cần được thực hành và trau chuốt, giống như viết mã.


2

IMHO, cái đầu tiên phù hợp để bình luận về những gì một lớp làm hoặc ở phần đầu của một tệp nguồn; cái thứ hai thích hợp để mô tả những gì khối mã sau đây làm. cho các phương thức, tôi sẽ sử dụng

//////////////////////////////////////////////////////////////////////
This code prints a basic "Hello world" message to the console screen. You can change the text in the brackets. 

Ngoài những câu trả lời tuyệt vời khác, tôi nghĩ sự nhất quán trong phong cách bình luận là một điểm khác. Nếu bạn sử dụng các loại kiểu bình luận khác nhau cho cùng một loại nhiệm vụ sẽ làm tổn hại đến khả năng đọc mã của bạn khá tệ.


1

Ví dụ bạn đưa ra là một chút cực đoan, nhưng vâng, ý kiến ​​có một chức năng rất quan trọng.

Người viết mã có một mô hình tinh thần về những gì nó cần làm. Các ý kiến ​​phục vụ cho

  • truyền đạt tới người đọc mô hình tinh thần đó là gì và
  • thể hiện ánh xạ giữa mô hình tinh thần và cách mã thực hiện nó.

Theo cách đó, nếu các yêu cầu thay đổi, nhiều khả năng các thay đổi tương ứng đối với mã có thể được thực hiện chính xác, bởi tác giả gốc hoặc bất kỳ ai đi sau.

Cũng tốt để thử viết mã theo cách mà nó tự giải thích, nhưng điều đó hiếm khi thành công 100%, vì vậy các ý kiến ​​là cần thiết.


0

Một câu trả lời nhanh cho câu hỏi là có Có. Nhận xét và phong cách bình luận rõ ràng ảnh hưởng đến khả năng đọc và dễ hiểu của mã. Đó là ý tưởng chung, nhưng chất lượng của các mô tả bình luận và thiết kế của họ hoàn toàn chủ quan.

Bạn đã bao giờ thử đọc mã và bình luận của người khác chưa? Hầu hết các lập trình viên viết mã và nhận xét dựa trên phong cách và trình độ kiến ​​thức của riêng họ. Đọc bình luận và mã của họ giống như cố gắng đi vào tâm trí của họ và làm theo thực tiễn của họ.

Một cách để tránh vấn đề này là sử dụng một nguyên tắc / hướng dẫn phong cách cơ bản, mô tả ngắn gọn các hướng dẫn cơ bản về cấu trúc mã, mục đích và nhận xét. Hướng dẫn này phải được tuân thủ một cách nhất quán bởi những người viết mã và tất cả những người còn lại có thể đọc mã và có thể mở rộng nó.


0

Về mặt phong cách, tôi sẽ đi với hai dạng nhận xét (đối với C ++ / Java)

/**
 * Multi-line comment
 */

hoặc là

// Single-line comment

một IDE với tô sáng cú pháp là đủ để thu hút sự chú ý của bạn vào bình luận, bạn không cần phải thích thú với định dạng.


0

Vâng, phong cách bình luận chắc chắn ảnh hưởng đến khả năng đọc. Bất kỳ kiểu nhận xét nào cho phép tôi xác định nhận xét nhanh chóng để tôi có thể tránh đọc chúng sẽ giúp ích rất nhiều khi điều tôi thực sự cố gắng làm là đọc .

Thậm chí tốt hơn là một kiểu nhận xét mã cho phép tôi sử dụng IDE giảm thiểu các bình luận ngay lập tức khỏi tầm nhìn, vì vậy tôi không phải tiêu tốn năng lượng để đọc xung quanh chúng.

Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.