Các nghiên cứu về tăng / giảm năng suất tài liệu mã

Sau nhiều tìm kiếm, tôi đã không trả lời được một câu hỏi cơ bản liên quan đến một giả định được biết đến trong thế giới phát triển phần mềm:

NHỮNG GÌ ĐƯỢC BIẾT:

Việc thực thi một chính sách nghiêm ngặt về tài liệu mã đầy đủ (có thể là thẻ Doxygen, Javadoc hoặc đơn giản là rất nhiều ý kiến) bổ sung thêm thời gian cần thiết để phát triển mã.

NHƯNG:

Có tài liệu kỹ lưỡng (hoặc thậm chí là API) mang lại khả năng tăng năng suất (một giả định) cho các nhà phát triển mới và dày dạn khi họ thêm tính năng hoặc sửa lỗi trên đường.

CÂU HỎI:

Là thời gian phát triển bổ sung cần thiết để đảm bảo tài liệu đó được bù đắp bằng mức tăng năng suất đi xuống (theo nghĩa kinh tế nghiêm ngặt)?

Tôi đang tìm kiếm các nghiên cứu trường hợp, hoặc câu trả lời có thể mang theo bằng chứng khách quan hỗ trợ cho các kết luận được rút ra.

Cảm ơn trước!

Bài viết "Phong cách đánh máy không chỉ là mỹ phẩm" khá cũ nhưng nó rất thú vị: http://portal.acm.org/cites.cfm?id=78611 .

Đã cũ, nó không bao gồm tất cả những thứ ưa thích có thể có trong những ngày này nhưng nó cho thấy rõ rằng tài liệu mã có vấn đề.

Đối với những người, giống như tôi, không có quyền truy cập vào thư viện kỹ thuật số ACM, họ đã tạo ra hai nhóm lập trình viên và đưa cho họ cùng một mã để nghiên cứu. Nhóm A chỉ nhận được mã với các bình luận thông thường, nhóm B nhận được một danh sách được in khá đẹp với mục lục, tham chiếu chéo và tất cả các chi tiết có thể có từ năm 1990.

Sau đó, họ yêu cầu hai nhóm thực hiện một số nhiệm vụ nhất định trên mã (ví dụ: mở rộng hàm, tìm lỗi, ...) và chấm điểm cho họ về tốc độ và chất lượng của các câu trả lời.

Để cân bằng nhóm, họ có cùng số lượng chuyên gia và lập trình viên cơ sở.

Chà, hóa ra nhóm B (nhóm có danh sách được in khá tốt) đã đạt điểm cao hơn nhóm A trong nhiều bài kiểm tra. Và, trong các trường hợp cụ thể, chỉ những chuyên gia nhất của nhóm A mới vượt qua được lập trình viên cơ sở của nhóm B.

Bài báo nói nhiều hơn nhưng đây là những gì tôi có thể nhớ lại từ bộ nhớ (tôi vẫn nên có bài viết được in ở đâu đó).

Đối với tôi ít nhất, dường như rõ ràng rằng mã có thể đọc được đáng giá hơn nhiều so với tài liệu chỉ phục vụ để bù cho mã được viết kém. Tôi có xu hướng coi các bình luận trong mã là một thách thức để xem liệu tôi có thể xóa bình luận bằng cách viết lại mã và làm cho nó tự giải thích hơn.

Tôi không thể ủng hộ điều đó bằng bất kỳ bằng chứng cứng nhắc nào, ngoại trừ lẽ thường, thông thường.

Tôi không có nghiên cứu nào để trích dẫn, nhưng tôi có một quy tắc đơn giản: nếu tôi quay lại mã của mình hai tuần sau đó và không thể biết ngay tôi đã làm gì, nó cần thêm ý kiến ​​hoặc cần được đơn giản hóa .

Chắc chắn, cách mã của bạn hoạt động nên được ghi lại bằng chính mã. Nhưng thời gian dành cho việc viết bình luận giải thích một cách cẩn thận và ngắn gọn lý do tại sao mã của bạn được viết theo cách gần như chắc chắn sẽ tự trả tiền trong thời gian dài, ngay cả khi bạn là người duy nhất duy trì mã.

Thời gian tồn tại của một phần mềm sẽ được dành phần lớn trong giai đoạn bảo trì, do đó, bất cứ điều gì giúp lập trình viên đến sau khi bạn hiểu những gì đang xảy ra sẽ gần như chắc chắn mang lại lợi nhuận tài chính, bởi vì nó giúp nhà phát triển tăng tốc nhanh hơn.

Trên bất kỳ API nào là tài liệu không tầm thường, API trong mã chỉ là vô dụng. Điều này là do sức mạnh trong API đến từ cách nó hoạt động cùng một đơn vị (không phải cách các phương thức / đối tượng riêng lẻ hoạt động).

Do đó, hữu ích hơn tài liệu thật là một tài liệu giống như sách dạy nấu ăn giải thích các kiểu sử dụng dự kiến ​​của API và các ví dụ về cách giải quyết một số tình huống rõ ràng (sử dụng phần lớn (không phải 100%) API).

Quyết định cho dù một phương thức nhất định là, không có các công cụ có thể chưa được phát minh, quá chủ quan để yêu cầu tài liệu đó được viết.

Bất kỳ thực tiễn dự đoán tốt nhất nào, chẳng hạn như "tất cả các phương thức công khai" hoặc tất cả các lớp trong một gói nhất định, v.v., có thể giúp ích nhưng quá thô sơ để đề xuất ngoài các trường hợp sử dụng cụ thể.

Đề xuất của tôi: Dạy cho các nhà phát triển của bạn thực hành tốt, cách xác định các phương pháp quan trọng đối với tài liệu (API chính thức hoặc không chính thức, thường được sử dụng, phương pháp sơ khai, phức tạp hoặc bí truyền) và để chúng tự quản lý.

(Liên quan chặt chẽ: Có thể có quá nhiều tính đồng nhất trong các tiêu chuẩn mã hóa không? )

^{Những lời xin lỗi mà tôi không có bất kỳ nghiên cứu nào để trích dẫn, nhưng tôi nghi ngờ rằng đây là vấn đề mà bất kỳ nỗ lực nào để đo lường nó sẽ ảnh hưởng quá lớn đến kết quả để đưa ra kết luận chung.}

Tôi nghĩ rằng chúng ta cần tách mã "thông thường" khỏi các API công khai về mặt này. Đối với mã thông thường, tôi đã rất đồng ý với hầu hết những người trả lời khác trong mã đó nên tự viết tài liệu và đọc gần giống như văn xuôi . Nếu mã của tôi không như vậy, thì đó thường là lỗi của tôi, vì vậy thay vì viết tài liệu, nó nên được cấu trúc lại. Các phương pháp nhỏ chỉ làm một việc tại một thời điểm, hoạt động ở một mức độ trừu tượng duy nhất, có một tên chính xác và mô tả , có thể đi một cách tuyệt vời để đạt được điều này.

Vấn đề với ý kiến ​​là họ thối. Ngay khi bạn thêm một nhận xét, nó bắt đầu sống một cuộc sống độc lập với mã mà nó đi kèm. Làm thế nào lớn cơ hội là nhà phát triển tiếp theo sửa đổi mã cũng sẽ cập nhật mạnh mẽ các nhận xét liên quan? Theo kinh nghiệm của tôi, gần bằng không. Kết quả cuối cùng sau một vài sửa đổi là các câu đố bình luận hoặc đánh lừa mọi người thay vì giúp đỡ họ.

Các ngoại lệ có thể là mã được tối ưu hóa hiệu suất hoặc sử dụng một thuật toán cụ thể . Trong trường hợp này, rất hữu ích khi thêm nhận xét để mô tả lý do tại sao mã trông giống như vậy, tham chiếu đến thuật toán, v.v.

Công việc tinh thần về chủ đề này là Clean Code .

OTOH một API công khai thực sự cũng phải được ghi lại trong Javadoc . Vì nó có thể được sử dụng bởi vô số người lạ với các kỹ năng và giả định rất đa dạng, người ta phải thực hiện bất kỳ biện pháp phòng ngừa nào để làm cho nó đơn giản và không mơ hồ để sử dụng càng tốt. Đó vẫn chủ yếu là một câu hỏi về thiết kế API phù hợp, nhưng cũng có một vai trò quan trọng đối với tài liệu.

Vấn đề là liệu bạn có tiết kiệm thời gian hay không bằng cách ghi lại mã của mình so với mọi nhà phát triển tiếp theo phải cố gắng tìm ra những gì đang làm. Nếu mã của bạn bay qua đánh giá mã mà không có ai đưa ra bất kỳ câu hỏi nào về những gì nó làm, thì có lẽ bạn đang ở trong tình trạng tốt. Không quá khó để mô tả các giả định bạn đưa ra về đầu vào. Giả sử phương thức của bạn lấy một đối tượng số nguyên và trả về một đối tượng chuỗi. Int có thể là null? Có giá trị tối thiểu / tối đa (bên cạnh số nguyên.MinValue / MaxValue) không? Nó có thể trả về một chuỗi rỗng hoặc null? Nó có ném ngoại lệ nào không? Tất nhiên bất cứ ai cũng có thể tìm thấy những thứ này bằng cách kiểm tra, nhưng nếu đủ các nhà phát triển khác sẽ sử dụng mã của bạn, thì việc tiết kiệm mỗi vài phút cũng rất đáng để bạn dành thời gian. Ngoài ra, nó giúp người kiểm tra nhanh chóng tạo ra các bài kiểm tra để xác nhận mã của bạn.

Đây chắc chắn là một chủ đề thú vị vì luôn có tranh luận về việc nhà phát triển có nên dành thời gian tạo hoặc duy trì tài liệu hay không nhưng thực tế là mã đó phải được viết tốt và được nhận xét rất tốt, theo cách này khi nhà phát triển truy cập lại mã hơn anh ta hoặc cô ta không phải mất thời gian suy nghĩ về cách viết mã và những gì nó được cho là sẽ làm ngay từ đầu nếu thành viên nhóm mới gia nhập nhóm hơn anh ta cũng có thể hiểu chức năng và hoạt động của mã vì nó đã được ghi lại rõ ràng.

Vì vậy, mã phải được nhận xét rất tốt và do đó nên là mã tự ghi mà không yêu cầu bất kỳ tài liệu bên ngoài.

Trong sự nghiệp của mình, tôi đã thấy mã với các mức độ khác nhau của tài liệu và chất lượng (lưu ý rằng tài liệu và chất lượng là mối quan tâm trực giao). Tôi muốn thời gian dành cho tài liệu được sử dụng để cải thiện chất lượng. Đối với trường hợp đơn giản, có những công cụ như GhostDoc có thể xem xét một chức năng và tạo bình luận doc cho bạn. Nếu GhostDoc có thể tạo ra một nhận xét có ý nghĩa cho biết chức năng của bạn làm gì, thì rõ ràng bạn đã đạt được mục tiêu có các chức năng được đặt tên tốt.

Trong nhiều trường hợp, GhostDoc thậm chí không thể bắt đầu cho bạn biết chức năng thực sự làm gì. Thời gian của bạn tốt hơn dành cho việc giải quyết vấn đề đó và (có thể) sử dụng ghostdoc để tự động tạo mã của bạn.

Xem Clean Code và PPP từ Bob Martin để thảo luận sâu hơn.