Bạn nên ghi chép lại mọi thứ hay chỉ nhất?

Có vẻ như một chủ đề gây tranh cãi để ghi lại tất cả mọi thứ, bao gồm cú pháp "JavaBean" của các getters và setters cho các trường: Mọi người nói rằng việc phá vỡ DRY lâu dài và lặp đi lặp lại (không lặp lại chính mình) , rằng quy ước đặt tên sẽ giải thích mọi thứ , và nó cắt mã / tài liệu. Đôi khi những lý lẽ đó hoạt động. Nhưng lần khác, bạn kết thúc với điều này:

Trên đây là phổ biến cho các dự án nguồn mở mạnh dạn tuân theo các nguyên tắc đó. Bạn còn lại với tài liệu hoàn toàn vô dụng . Điều đó không giải thích bất cứ điều gì về những gì đang diễn ra bên dưới, những tác động có thể xảy ra hoặc thậm chí giá trị mong đợi là gì (nó có thể là null hoặc không bao giờ null? Tôi không biết; Javadoc không cho tôi biết).

Vậy khi nào tôi nên làm tài liệu? Tôi có tài liệu mọi thứ ngay cả khi nó thỉnh thoảng mã hóa? Hay tôi không ghi nhận điều gì vì trong mắt tôi nó "rõ ràng"?

Tài liệu mọi thứ có ý nghĩa với tài liệu .

Trong một thế giới lý tưởng, vâng, bạn sẽ ghi lại tất cả mọi thứ. Tuy nhiên, trên Trái đất, chúng tôi có thời hạn, cắt giảm tính năng, gia đình và bạn bè đến thăm, kỳ nghỉ sẽ diễn ra, chỉ 24 giờ trong một ngày và chỉ 365 ngày trong một năm. Không có đủ thời gian để ghi chép lại mọi thứ. Vì vậy, tối ưu, ghi lại tất cả mọi thứ bạn có thể (bạn sẽ không hoàn thành), nhưng hãy tận dụng tối đa lợi ích của bạn bằng cách:

• Làm cho mã có thể đọc được và chữ ký phương thức càng rõ ràng càng tốt để tài liệu ít có khả năng cần thiết hơn.
• Tài liệu những điều tối nghĩa nhất đầu tiên. Giúp đỡ những người khác bằng cách ghi lại những vụ hack điên rồ mà bạn phải làm để đưa mọi thứ ra khỏi cửa.
• Ghi lại lý do tại sao trước những gì - Đừng bình luận những gì làm, như "Lặp lại hồ sơ khách hàng trong đó số dư nhỏ hơn 0 và xếp hạng nhỏ hơn một và thêm chúng vào danh sách khách hàng được miễn". Tài liệu lý do tại sao bạn thêm chúng vào danh sách bằng tiếng Anh đơn giản (hoặc ngôn ngữ của nhóm bạn), như "Vì những khách hàng này có số dư âm và xếp hạng thấp, họ đang khiến chúng tôi mất tiền, vì vậy loại trừ họ không thể kiểm tra.

Tiếp tục ghi chép cho đến khi bạn có thể xem người khác đọc nó mà không cảm thấy cần phải giải thích bất cứ điều gì.

Tuần trước có một bài viết tuyệt vời liên quan đến tài liệu tại The Daily WTF. Tôi nghĩ rằng nó nói tất cả mọi thứ, vì vậy tôi sẽ chỉ để lại liên kết:

http://thed Dailywtf.com/Articles/Documentation-Done-Right.aspx

Về cơ bản nó nói rằng bạn không nên ghi lại một cái gì đó nếu nó không hữu ích (một số tài liệu chỉ còn lại để thối trong ngăn kéo) và ghi lại lượng thông tin ít nhất cần thiết để hiểu một phần nhất định của dự án. Quá nhiều tài liệu chỉ khiến người đọc bối rối.

Thực sự phụ thuộc vào mức độ dễ đọc của mã đối với khán giả đọc nó. Chỉ ra ai là khán giả để đọc mã của bạn và có ai đó đáp ứng hồ sơ đó đọc mã của bạn.

Một cách tiếp cận khác là xem lại mã của chính bạn sau một tuần và xem bạn có hiểu những gì bạn đã làm không, nếu không, hãy ghi lại mã và xem lại mã trong hai tuần hoặc lâu hơn.

Mặc dù tôi đánh giá cao một tài liệu rõ ràng và rộng rãi, nhưng không có gì giống như mã tự viết tài liệu. Vì vậy, điểm mấu chốt (đối với tôi) là:

Rất nghi ngờ về tài liệu (mã nguồn); hãy thử và làm cho nó trở nên dư thừa bằng cách cải thiện mã, nhưng đừng né tránh việc ghi chép rõ ràng và đầy đủ khi cần thiết.

Tất nhiên, trong một số trường hợp nhất định, tài liệu có thể được yêu cầu vì những lý do khác ngoài 'giải thích mã đang làm gì' (ví dụ: cơ sở nhóm lớn, tiêu chuẩn tổ chức, v.v.).

Đề nghị của tôi về tài liệu là nếu có bất cứ điều gì lạ mắt trong mã, thì đó là tài liệu cần được cập nhật. Fancy là đối tượng của nhiều giải thích, trong tâm trí của tôi là nơi mà một cái gì đó được thực hiện theo một cách cụ thể có thể có tác dụng phụ cần được lưu ý, ví dụ như một cái gì đó có thể được thực hiện để đệ quy để đảm bảo rằng các mục cháu được xử lý thông qua một cây nút để thực hiện một số thử nghiệm trên tất cả các hậu duệ. Nói rõ tại sao một cái gì đó được thực hiện theo một cách cụ thể có thể là một cách tốt để biết liệu có lý do chính đáng để sử dụng một cái gì đó hay không.

Nói một cách đơn giản, tài liệu có sẵn để giúp các nhà phát triển bây giờ và các nhà bảo trì trong tương lai.

Nếu bạn nhớ câu châm ngôn đơn giản đó, thì mức độ tài liệu sẽ tự xác định.

Tài liệu, vì lợi ích của tài liệu, là một sự lãng phí thời gian ... nhưng giải thích ngày nay những gì bạn đang làm là hữu ích hơn so với việc ai đó phải thiết kế lại mã của bạn trong năm năm.

Cá nhân tôi đi với cách tiếp cận xem xét tài liệu mọi thứ. Tức là trong khi mã hóa tôi xem xét tại mọi thời điểm liệu tài liệu sẽ thêm giá trị. Hầu hết thời gian câu trả lời là có cho chính xác các loại ràng buộc và kiến ​​thức tên miền được đề cập trong câu hỏi ban đầu. Ví dụ: null-ability, các ràng buộc duy nhất, giải thích trường trong miền rộng hơn.

Để tránh trùng lặp, tôi có xu hướng tài liệu nhiều về các lớp API chính với loại thông tin này. Sau đó, chỉ thực hiện tài liệu và nội bộ nơi có hành vi không rõ ràng hoặc không nhất quán. Tôi thấy điều này hoạt động tốt vì đó là những người sử dụng API cần sự trợ giúp và tài liệu nhiều nhất, nói chung là an toàn khi giả định mọi người sửa đổi việc triển khai biết API nên có kiến ​​thức này.

Tôi cũng có xu hướng chỉ tài liệu các getters. Tôi không sao chép tài liệu vào setters, định nghĩa trường và tham số hàm tạo. Tôi chỉ ghi lại hành vi không rõ ràng như mặc định ở những nơi này. Bất kỳ hành vi nào có thể được suy ra từ tài liệu getter đều không được ghi lại. Ví dụ: nếu getter được ghi lại là null không bao giờ trả về, tôi thường không tài liệu rằng bạn không thể chuyển null cho setter, trừ khi có mặc định.

Một số người thích đánh dấu hành động "xem xét tài liệu" này bằng cách thêm các bình luận trống trong đó họ đã xem xét tài liệu nhưng thấy không cần thiết. Tôi không thích cách làm này vì nó chỉ làm lộn xộn mã và cản trở.