Là ý kiến ​​được coi là một hình thức của tài liệu?

Khi tôi viết các tập lệnh nhỏ cho chính mình, tôi xếp chồng mã của mình lên cao bằng các bình luận (đôi khi tôi nhận xét nhiều hơn mã tôi). Rất nhiều người tôi nói để nói rằng tôi nên ghi chép lại các kịch bản này, mặc dù chúng là cá nhân, vì vậy nếu tôi từng bán chúng, tôi sẽ sẵn sàng. Nhưng không bình luận một dạng tài liệu?

Sẽ không thế này:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

được xem là tài liệu, đặc biệt nếu nhà phát triển đang sử dụng mã của tôi? Hoặc tài liệu được coi là nằm ngoài chính mã?

Bình luận chắc chắn là tài liệu. Đối với hầu hết các dự án, các ý kiến ​​(không may) là hình thức chính (nếu không chỉ) của tài liệu dự án. Vì lý do này, nó rất quan trọng để làm cho đúng. Bạn cần đảm bảo rằng tài liệu này vẫn chính xác mặc dù mã thay đổi. Đây là một vấn đề phổ biến với ý kiến. Các nhà phát triển thường "điều chỉnh" chúng khi họ làm việc trong mã quen thuộc, vì vậy họ quên cập nhật nhận xét để phản ánh mã. Điều này có thể tạo ra những bình luận lỗi thời và sai lệch.

Rất nhiều người đề nghị làm cho mã tự ghi lại. Điều này có nghĩa là thay vì nhận xét, bạn cấu trúc lại mã của mình để loại bỏ sự cần thiết cho chúng. Điều này có thể loại bỏ hầu hết các bình luận "cái gì" và "làm thế nào", nhưng không thực sự giúp với các bình luận "tại sao". Mặc dù điều này có thể hoạt động hiệu quả để loại bỏ hầu hết các bình luận, nhưng vẫn có nhiều lúc viết bình luận là cách đơn giản và hiệu quả nhất để ghi lại một đoạn mã.

Chúng là một dạng tài liệu, nhưng hãy nhớ rằng tài liệu nằm trong mắt của kẻ si tình ....

• Đối với một số người, tự viết mã là đủ. Nhưng điều đó giả định một mức độ chi tiết kỹ thuật là khách hàng. Chúng ta nên cẩn thận nghĩ rằng điều này là đủ, bởi vì bản ngã của chúng ta có thể cho chúng ta biết "Rõ ràng những gì mã này đang làm" nhưng thời gian có thể chứng minh điều khác. Nó cũng giả định rằng bạn biết trước các kỹ năng của người đọc.

• Đối với những người nhìn vào mã nguồn nhưng với chuyên môn kỹ thuật ít hơn, các bình luận có thể ổn. Nhưng điều đó giả định rằng ai đó đang xem mã nguồn.

• Nếu bạn là người kỹ tính, nhưng thiếu thời gian để đọc tất cả mã nguồn, một hướng dẫn kỹ thuật có thể là những gì cần thiết.

• Nếu người dùng thiếu kỹ năng kỹ thuật, nhưng chỉ cần biết những gì đang xảy ra, tài liệu người dùng là những gì cần thiết.

Vậy câu hỏi thực sự là khách hàng của bạn là ai? Nếu bạn là như vậy, sau đó tự viết mã tài liệu hoặc ý kiến ​​là đủ. Nếu đó là cho người khác, bạn có thể muốn mở rộng cách bạn tài liệu.

Vâng, ý kiến ​​là một hình thức của tài liệu. Cho dù chúng có phải là tài liệu hữu ích cho người phải duy trì hoặc cập nhật mã của bạn hay không là một câu hỏi mở.

Tôi biết bạn có ý đó như một ví dụ vứt đi, nhưng những thứ như

print $foo; # this prints "bar"

không hữu ích; nó chỉ thêm lộn xộn thị giác. Đừng tài liệu rõ ràng.

Chặn nhận xét ở phần đầu của một phương thức hoặc định nghĩa hàm mô tả mục đích của hàm hoặc phương thức (theo thuật ngữ cấp cao ), đầu vào, đầu ra, giá trị trả về (nếu có), ngoại lệ (nếu có), điều kiện tiên quyết và hậu điều kiện là hữu ích, nhưng chỉ ở mức độ mà họ nói với ai đó về cách sử dụng chức năng hoặc phương thức. Họ không giải thích tại sao chức năng tồn tại.

Nếu ai đó cần duy trì mã của bạn, thì bạn cần ghi lại các yêu cầu và thiết kế ở đâu đó và điều đó thường không được thực hiện trong chính mã nguồn.

Tôi thấy gắn bó với cách tiếp cận của Bob Martin về vấn đề này, từ Clean Code, thường giải quyết vấn đề liệu bạn có nghĩ rằng bạn đang bình luận quá mức hoặc đang bình luận và bỏ qua tài liệu:

Chúng tôi là tác giả. Và một điều về tác giả là họ có độc giả. Thật vậy, các tác giả có trách nhiệm giao tiếp tốt với độc giả của họ. Lần tới khi bạn viết một dòng mã, hãy nhớ rằng bạn là một tác giả, viết cho những người đọc sẽ đánh giá nỗ lực của bạn.

... Tỷ lệ thời gian dành cho việc đọc so với viết là hơn 10: 1. Chúng tôi liên tục đọc mã cũ như một phần của nỗ lực viết mã mới.

Vì vậy, nói cách khác, mã của bạn là tự giải thích mà không cần tài liệu? Không có quy tắc nào được đặt ra cho nó (trừ khi bạn làm việc cho ai đó như Microsoft có tài liệu có thể truy cập công khai), chủ yếu là giúp người đọc mã tương lai thường là bạn.

Tài liệu nên ghi lại lý do tại sao không như thế nào . Các Làm thế nào nên hiển nhiên trong các mã, có nghĩa là trừ khi đó là một số thủ thuật tối ưu hóa phức tạp hoặc kỹ thuật ngôn ngữ cụ thể khác mà không phải là thường xảy ra.

Các sao có lẽ không phải ở trong mã, nó nên ở nơi khác như một tồn đọng sản phẩm, đó là gắn với cam kết ý kiến với id câu chuyện có thể được tìm kiếm trong một bản ghi thay đổi hoặc tên chi nhánh.

Bình luận là một hình thức của tài liệu. Một hình thức kém hơn và một hình thức gợi ý rằng bạn đã xác định được một khu vực mã của bạn có thể được bao gồm tốt hơn.

Có vẻ như bạn nhận xét mọi thứ bắt buộc. Có các lựa chọn khác có thể là một điều tốt. Tôi có thể nghĩ về ba hình thức tài liệu ưu việt:

1) Yếu tố mã của bạn tốt hơn. Thay vì thêm vào một bình luận, hãy trích xuất một phương thức hoặc hàm có tên là văn bản của bình luận mà bạn sắp viết. Vì vậy, mã nói những gì bình luận của bạn sắp nói.

2) Các xét nghiệm. Đây là hình thức tài liệu tôi thường tìm kiếm. Kiểm tra đơn vị và kiểm tra chấp nhận là tài liệu sống và có thể đọc dễ dàng nếu nhiều phương pháp có ý nghĩa được sử dụng để thể hiện ý định, như trong điểm 1.

3) Đối với tập lệnh, tùy chọn --help. Đây là nơi bạn có thể đi hạt trên doc. Dính vào các ví dụ, dự đoán những gì người dùng sẽ cần.

Tóm lại, nếu bạn thấy mình có xu hướng dính vào một bình luận, hãy kiểm tra xem có cách nào để giao tiếp với người đọc bằng cách cấu trúc mã tốt hơn không. Hoặc có một bài kiểm tra truyền đạt lý do tại sao mã đó ở đó? Nếu bạn vẫn cảm thấy có xu hướng bình luận nó, hãy thừa nhận thất bại và làm điều đó.