Đọc javadoc có thích đọc mã nguồn hơn để làm quen với thư viện không?

Tôi chỉ bắt gặp những điều sau đây trong sổ tay phòng thí nghiệm tại trường đại học:

Bạn cần nghiên cứu giao diện của các lớp bằng cách tạo javadoc cho chúng để bạn biết các hoạt động được cung cấp (hãy xem mã, nhưng khi sử dụng mã của người khác, như ở đây, bạn nên làm việc từ javadoc chứ không phải mã bất cứ khi nào có thể).

Tôi không hiểu tại sao lại như vậy; vì javadoc có thể bị lỗi thời hoặc có thể mô tả chức năng của mã không tốt. Chắc chắn nhìn vào mã nguồn, và đọc các bình luận javadoc là tốt nhất?

Có một lý do tại sao, hoặc một trường hợp khi chỉ đọc javadoc là điều tốt nhất để làm?

source-code comments javadocs

— Todd Davies
nguồn

Trong phần lớn các trường hợp, bạn sẽ không có cơ hội đọc và hiểu tất cả các mã bạn cần. Nó cũng có thể không rõ ràng từ mã cách xử lý các trường hợp cạnh.

— raptortech97

điều này đã được hỏi và trả lời nhiều lần trước đó, bắt đầu bằng câu hỏi đầu tiên tại trang web này - Nhận xét là một mã mùi mùi và nhiều câu hỏi liên quan đến nó

— gnat

Câu trả lời:

Đề xuất có lẽ là về lập trình cho một giao diện chứ không phải là việc thực hiện .

Chắc chắn, nếu bạn có quyền truy cập vào mã thì không có gì ngăn bạn nhìn vào việc triển khai để hiểu cách thức hoạt động của nó. Nhưng bạn phải luôn đảm bảo rằng cách thức không ảnh hưởng đến mức tiêu thụ API của bạn.

Khi bạn đang sử dụng API, bạn đang làm việc chống lại sự trừu tượng. Cố gắng chỉ quan tâm đến những gì API cung cấp (hợp đồng) chứ không phải cách thức (việc triển khai).

Điều này là do không có gì đảm bảo rằng việc triển khai API sẽ không thay đổi mạnh mẽ từ phiên bản này sang phiên bản tiếp theo, ngay cả khi hợp đồng vẫn không thay đổi.

— Siêu tốc
nguồn

Một trong những thiếu sót lớn nhất trong nhiều tài liệu của lớp là một đặc điểm rõ ràng về khía cạnh nào trong các hành vi rõ ràng của một lớp có thể được người tiêu dùng tin cậy một cách hợp pháp (và không được thay đổi trong các phiên bản tương lai của lớp), và những hành vi nào có thể là hợp pháp thay đổi và do đó có thể không được dựa một cách hợp pháp. Ví dụ, mặc dù bộ sưu tập bản đồ cung cấp bất kỳ thứ tự liệt kê nào được đảm bảo sau khi bất kỳ mục nào bị xóa, nhưng giá rẻ để đảm bảo rằng miễn là không có mục nào bị xóa, các mục sẽ được liệt kê theo thứ tự chúng được thêm vào.

— 4/2/2015

Có nhiều trường hợp mã có thể cần xây dựng bộ sưu tập ánh xạ từ một chuỗi các mục và xử lý các mục sau đó trong chuỗi ban đầu. Nếu bộ sưu tập đảm bảo rằng các mục sẽ liệt kê theo trình tự chúng được thêm vào, trình tự ban đầu có thể bị từ bỏ một cách an toàn, nhưng trong trường hợp không có sự đảm bảo như vậy, nó phải được giữ lại. Ghi lại một hành vi mà lớp sẽ "tự nhiên" tuân theo sẽ không tốn chi phí thực hiện, nhưng sẽ làm cho lớp trở nên hữu ích hơn.

— 4/2/2015

@supercat: Điều đó hạn chế sau đó điều chỉnh / viết lại lớp. Điều đó có nghĩa là bất kỳ quyết định đáng tiếc nào không bao giờ có thể được sửa chữa.

— Ded

@Ded repeatator: Có sự đánh đổi; câu hỏi được đặt ra là liệu nó có đáng để đưa ra một lợi ích tiềm năng cho người tiêu dùng để tạo điều kiện cho một số loại thay đổi triển khai tiềm năng nhất định hay không. Tôi sẽ đề xuất rằng nguyên tắc YAGNI sẽ ưu tiên mang lại cho người tiêu dùng lợi ích trừ khi người ta thực sự có thể nói rõ các loại thay đổi mà họ muốn thực hiện và người ta sẽ không thể điều chỉnh hiệu quả những thay đổi đó mà không từ chối lợi ích của người tiêu dùng. Ngoài ra, người ta có thể có một AddOnlyDictionarylời hứa sẽ duy trì thứ tự chèn và cung cấp ...

— supercat

... An toàn luồng đa người đọc một người viết, hoặc hình dung rằng nếu có thể cần loại từ điển khác thì họ có thể bắt nguồn từ đó Dictionaryvà mọi người có thể chuyển sang cái mới khi viết mã không cần hành vi cũ. Lưu ý rằng khả năng giữ gìn trật tự bổ sung không phải là thường có liên quan đối với mã mà nhận được một Dictionarytừ nơi khác (kể từ một cuốn từ điển nhận được từ nơi khác có thể có một mục bị xóa tại một số điểm), nhưng chỉ cho mã mà tạo ra các trường hợp thông qua các nhà xây dựng. Trong mọi trường hợp, nếu một từ điển sẽ không tôn trọng một bảo đảm bổ sung ...

— supercat

Ngoài sự khác biệt giữa giao diện và cách triển khai, đã được giải thích trong câu trả lời trước , có một khía cạnh quan trọng khác: độ phức tạp .

Hệ thống thực tế thường phức tạp. Nếu bạn bắt đầu đọc qua mã của một lớp, bạn sẽ thấy rằng bạn cũng nên đọc và đọc mã của một lớp khác, sau đó một lớp khác, v.v ... Vài giờ sau, bạn sẽ đơn giản bị mất trong sự phức tạp và sẽ không nhớ ai gọi cái gì và trong trường hợp nào.

Khi bạn chỉ sử dụng các ý kiến của giao diện, bạn giảm thiểu tất cả sự phức tạp này. Nó có thể là dưới mui xe, mọi thứ đều đơn giản. Hoặc có thể là dưới mui xe, hàng chục hoặc hàng trăm lớp tương tác với nhau, khiến cho thực tế không thể giữ toàn bộ hình ảnh trong đầu bạn.

Bạn có thể làm một thí nghiệm.

Tìm một phần trong OpenCV mà bạn quan tâm. Đọc qua tài liệu giao diện. Mất bao lâu để có thể nắm bắt những điều cơ bản và sử dụng hiệu quả thư viện?
Bây giờ nhìn vào việc thực hiện . Có bao nhiêu lớp được gọi trực tiếp bởi giao diện? Có bao nhiêu lớp được gọi bởi mỗi lớp? Có bao nhiêu dòng mã? Có bao nhiêu phương pháp? Bạn sẽ mất bao lâu để khám phá tất cả mã nguồn này trước khi có một ngăn xếp tràn vào não?

— Mourzenko
nguồn

Chính ma, đó phải là lý do tại sao các bản cập nhật mất nhiều thời gian và tại sao các lỗ hổng bảo mật có thể tồn tại quá lâu mà không bị phát hiện, bởi vì rất khó để xem xét việc thực hiện một chương trình tinh vi. Tôi đã cố gắng chỉ nhìn qua nguồn Java của hai học kỳ đầu tiên của khóa học lập trình Java. Tôi nghĩ rằng không có một lớp nào không gọi ít nhất 2 lớp khác và những lớp họ gọi cũng gọi bất kỳ số lớp nào. Tôi không bao giờ có thể đi theo một đoạn mã để hoàn thành cuối cùng. Nó chỉ đơn giản là mất quá nhiều thời gian và quá khó để theo dõi nơi tôi đang ở trong

— Progfram

Có một lý do tại sao, hoặc một trường hợp khi chỉ đọc javadoc là điều tốt nhất để làm?

Mặc dù bạn hoàn toàn chính xác rằng JavaDoc có thể đã lỗi thời hoặc xấu, nhưng nó có xu hướng ở định dạng tốt hơn để đọc bán buôn hơn mã trong IDE. Và quan trọng hơn, đó là ngôn ngữ tự nhiên. Đó là điều quan trọng đối với hai trường hợp:

Mọi người không quen đọc mã. Ví dụ, sinh viên đại học thường được phục vụ tốt hơn bằng cách đọc các mô tả ngôn ngữ tự nhiên của các chức năng hơn là cố gắng hiểu mã mà họ đang trong quá trình học.
Những người không sử dụng tiếng Anh (hoặc ngôn ngữ ít nhất sử dụng bảng chữ cái ngữ âm) làm ngôn ngữ chính. Vì JavaDoc có thể hoạt động với các ký tự mà số nhận dạng không thể, nên nó có thể cung cấp các mô tả tốt hơn về những gì đang xảy ra cho những người dùng đó. JavaDoc nói riêng dường như thậm chí có một số khả năng bản địa hóa tài liệu cho bạn .

Điều đó nói rằng, tôi là một người khá tin tưởng vào mã có thể đọc được. Đối với các nhà phát triển có kinh nghiệm, tôi hy vọng việc đọc mã sẽ là một cách tiếp cận tốt hơn hầu như mọi lúc nếu tùy chọn đó có sẵn.

— Telastyn
nguồn