Hướng dẫn cho người mới bắt đầu viết bình luận?

27

Có một hướng dẫn dứt khoát để viết bình luận mã, nhằm vào các nhà phát triển vừa chớm nở?

Lý tưởng nhất, nó sẽ bao gồm khi các bình luận nên (và không nên) được sử dụng, và những bình luận nào nên chứa.

Câu trả lời này :

Không bình luận bạn đang làm gì, nhưng TẠI SAO bạn đang làm điều đó.

WHAT được chăm sóc bằng mã sạch, dễ đọc và đơn giản với sự lựa chọn đúng tên biến để hỗ trợ nó. Nhận xét hiển thị cấu trúc cấp cao hơn cho mã không thể (hoặc khó) hiển thị bằng chính mã.

đến gần, nhưng nó hơi súc tích cho các lập trình viên thiếu kinh nghiệm (một bản mở rộng về điều đó với một số ví dụ và trường hợp góc sẽ là tuyệt vời, tôi nghĩ vậy).

Cập nhật : Ngoài các câu trả lời ở đây, tôi nghĩ câu trả lời này cho một câu hỏi khác có liên quan cao.

language-agnostic  comments 
— Cameron
nguồn
Tôi nghĩ rằng chúng ta đang nhanh chóng chuyển đến một thế giới nơi mọi người không bình luận gì nữa. Để tốt hơn (nhiều khả năng) cho tồi tệ hơn. Nhanh nhẹn.
— MK01
1
@MK: Nếu đó là trường hợp (tôi có xu hướng đồng ý nhiều hơn với câu trả lời này ), thì một hướng dẫn giải thích cách không viết bình luận, và tại sao chúng nên tránh, sẽ hữu ích như vậy. Như một vấn đề của thực tế, quan điểm càng khác nhau, tốt hơn.
— Cameron
Tôi nghĩ rằng những bình luận nhỏ để cải thiện tốc độ đọc mã rất hữu ích và sẽ luôn như vậy. Tôi không hoàn toàn mua lý do "bình luận cũ", ngay cả khi chúng đã cũ, chúng sẽ có giá trị lịch sử. Tôi đã từng làm việc trên một cơ sở mã mà thỉnh thoảng có các bình luận chi tiết ở đây và ở đó và chưa bao giờ tôi thực sự bị cắn bởi nhận xét đã hết thời.
— MK01
— gnat

Câu trả lời:

38

Bạn nên nhận thức được điểm yếu lớn nhất của các bình luận: chúng trở nên cũ kỹ. Đó là, khi thay đổi mã, các nhà phát triển hiếm khi cập nhật các bình luận để giữ đồng bộ với mã. Điều này có nghĩa là, bạn không bao giờ có thể tin tưởng họ và cuối cùng vẫn đọc được mã. Vì lý do này, mã của bạn nên được tự ghi lại. Bạn nên chọn chức năng và tên biến theo cách mà mã đọc giống như văn xuôi.

Vì vậy, đừng ghi lại những gì mã đang làm. Mã tự viết tài liệu nên chăm sóc điều đó. Tài liệu TẠI SAO bạn đang làm điều đó. WHY thường liên quan đến quy tắc kinh doanh hoặc kiến ​​trúc liên quan và sẽ không thay đổi thường xuyên và trở nên cũ kỹ nhanh chóng tại WHATs. Trường hợp cạnh tài liệu. Tài liệu ngoại lệ. Quyết định thiết kế tài liệu. Và quan trọng nhất là ghi lại những quyết định thiết kế mà bạn đã xem xét, nhưng quyết định không thực hiện (và tài liệu TẠI SAO bạn quyết định không sử dụng chúng).

2
Điều cuối cùng là rất quan trọng. Đôi khi có một lỗi / tác dụng phụ với việc thực hiện giải pháp rõ ràng. Tài liệu lý do tại sao bạn chọn đi cùng với một số giải pháp khác sẽ ngăn nhà phát triển tiếp theo giới thiệu lại lỗi khi họ "sửa" cho bạn giải pháp có vẻ kém.
— CaffGeek
2
Một điểm khác, công việc đầu tiên của tôi coi ý kiến ​​cũng quan trọng như mã. Cố gắng tập thói quen đọc bình luận cũng như mã khi bạn xem lại, và cố gắng nhấn mạnh rằng các bình luận sẽ được cập nhật bất cứ khi nào có thể. Điều này giúp tránh các bình luận trở nên cũ kỹ và giữ cho các quy tắc kinh doanh, vv được ghi lại trong mã của bạn cập nhật.
— Eric Hydrick
10

Bạn nên đọc cuốn sách Clean Code của Robert C. Martin . Nó giải thích độc đáo rằng nếu bạn cần bình luận, rất có thể bạn không viết mã đúng. Lý tưởng nhất, mã của bạn nên là "tự nhận xét." Cuốn sách Clean Coder giải thích cách thực hiện điều này, sao cho các bình luận là không cần thiết và nó đã mô tả tốt cách thực hiện các bình luận trong các tình huống cần thiết. (Chẳng hạn như giải thích một công thức toán học phức tạp)

— Bob
nguồn
Mặc dù tôi rất không muốn một công thức toán học phức tạp được giải thích như tôi muốn nó được viết ra bằng ký hiệu toán học thích hợp (có thể là TeX), với lời giải thích về tầm quan trọng và nguồn gốc của nó. Nếu bạn không hiểu công thức thì bạn không nên nhầm lẫn với mã sử dụng nó để tính toán một số giá trị nào đó, vì bạn đặc biệt có khả năng làm hỏng và đưa ra các lỗi (tinh tế hoặc không).
— CVn
Mã chỉ có thể nói như thế nào , không phải tại sao hay tại sao không . Bạn cần bình luận cho điều đó.
7

Code Complete, như đã đề cập, có nhiều hướng dẫn khác nhau về cách viết bình luận. Nói tóm lại, đó là PDL và có thể tóm tắt là:

  1. Mô tả ý định của bạn, không phải những gì mã đang làm. Tránh mô tả chi tiết triển khai trừ khi bạn đang sử dụng một số mẹo hoặc bạn đang sử dụng triển khai tùy chỉnh. Ví dụ, sử dụng các bit dịch chuyển để phân chia, sử dụng số học con trỏ để truy cập các thành viên của lớp hoặc sử dụng bộ cấp phát bộ nhớ tùy chỉnh cho một số đối tượng được gộp.

  2. Viết mã giả (nghĩa là các bình luận) trước, sau đó viết mã thực sau khi bạn đã mô tả xong thói quen / phương thức / hàm của bạn. Ngôn ngữ được sử dụng ở mức độ cao nhưng cụ thể, vì vậy nó có thể khá dài dòng

  3. Có ý tưởng về những gì mã của bạn đang làm ngay cả trước khi viết mã

  4. Có ý kiến ​​gần với mã thực tế

Mục đích là để tránh những bình luận dài dòng không liên quan có thể bị lỗi thời, nhưng để có những bình luận phản ánh ý định và mục đích của mã. Sử dụng mã giả cấp cao cũng giúp làm rõ suy nghĩ của bạn trước khi viết triển khai.

Có một liên kết tại GameDev.net [giải thích PDL] [1], trong trường hợp bạn không muốn theo dõi cuốn sách.

— Extrakun
nguồn
5
Viết mã giả (nghĩa là các ý kiến) trước . Tôi không thể không đồng ý nhiều hơn. Không có cách nào tốt hơn để đảm bảo các bình luận sẽ không khớp với mã. Các lập trình viên mới (và người hỏi đặc biệt yêu cầu hướng dẫn cho người mới bắt đầu) sẽ hack và tái cấu trúc các chức năng hàng trăm lần trước khi họ hài lòng với họ, mã sẽ được chuyển đi nhanh chóng, viết lại, tái sử dụng và cuối cùng, họ có thể có một giải pháp làm việc tao nhã, nhưng nó sẽ trông không giống mã giả ban đầu của họ. Các ý kiến ​​có được di chuyển và cập nhật khi họ nhận được mã để làm việc không? Bạn có thể đặt cược bippy ngọt ngào của bạn họ sẽ không. Hai xu của tôi.
— Nhị phân nhị phân
1
Ngoài ra, các nhận xét mã giả sẽ cho bạn biết mã phải làm gì. Các mã sẽ cho bạn biết rằng. Mã giả sẽ không cho bạn biết lý do tại sao mã đang làm điều đó. -1 anh bạn, xin lỗi, nhưng tôi không thể đồng ý với điểm thứ hai, thời gian đã thay đổi.
— Nhị phân nhị phân
1
Không tranh luận, nhưng nhiều lời giải thích - mã giả là để giải thích ý định của mã bạn đã viết. Có nghĩa là, nhận xét không phải là về chi tiết triển khai (Chẳng hạn như "Thêm x vào đầu ngăn xếp") mà là về những gì mã phải làm (chẳng hạn như "Làm cho cửa sổ xuất hiện trước mọi thứ khác"). Như bạn đã chỉ ra một cách đúng đắn, bạn cần di chuyển các bình luận với mã. Tôi không đồng ý với mã có thể cho bạn biết mã đang làm gì - mọi lúc. Ngay cả khi, một nhận xét hữu ích / chính xác (nếu tôi quản lý để viết nó tốt!) Đi một chặng đường dài. Cuối cùng, vẫn là IMHO.
— Extrakun
3
Một phương thức hoặc hàm được gọi showWindowOnTop(window)sẽ luôn tốt hơn một nhận xét có cùng bản chất, tất cả những điều này đã lỗi thời và lời khuyên tồi trong năm 2012. 1) Tên hàm / Phương thức mô tả ý định, 2) mã giả là bài tập rỗng với chuỗi công cụ hiện đại 3) Các thử nghiệm cho bạn biết mã phải làm gì trước khi bạn viết nó, 4) mã có tên tốt sẽ tốt hơn các nhận xét không khớp với mã được đặt tên kém
1

Đề nghị của tôi sẽ là viết một số mã mà không có bất kỳ bình luận nào, và sau đó bỏ đi. Hãy trở lại với nó trong một năm và đọc nó. Phần mà bạn không hiểu dễ dàng là phần bạn nên nhận xét.

— Kevin
nguồn
1
Hah, vâng ;-) Tuy nhiên, đây không phải là lời khuyên đặc biệt hữu ích - có lẽ đây nên là một nhận xét?
— Cameron
phần mà bạn không hiểu bạn nên viết bằng những phần nhỏ hơn được đặt tên tốt hơn. Các lý do chính được đưa vào mã là các hàm / phương thức dài và nên có nhiều phần tự viết tài liệu nhỏ hơn.
0

Tôi thực sự thích cách Evan Todd tóm tắt quan điểm của mình về các loại bình luận hữu ích duy nhất ( trích dẫn từ blog của anh ấy ):

  • Bình luận giải thích tại sao, hơn là những gì. Đây là những hữu ích nhất.
  • Nhận xét với một vài từ giải thích những đoạn mã khổng lồ sau đây làm gì. Đây là hữu ích cho điều hướng và đọc.
  • Nhận xét trong việc khai báo cấu trúc dữ liệu, giải thích ý nghĩa của từng trường. Chúng thường không cần thiết, nhưng đôi khi không thể ánh xạ một khái niệm theo trực giác vào bộ nhớ và các bình luận là cần thiết để mô tả ánh xạ.
— Cameron
nguồn
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 cookie và Chính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.