Tôi có nên ghi lại các phương pháp riêng tư của mình không?

Question

Tài liệu phương thức riêng tư chỉ có thể được xem bởi những người có quyền truy cập vào mã nguồn. Có đáng để nỗ lực dành cho nó không?

Answer 1

Cá nhân, tôi cảm thấy như vậy. Tài liệu thường hữu ích nhất cho các nhà phát triển trong tương lai, duy trì phần mềm của bạn - đặc biệt là tài liệu thành viên.

Thậm chí tài liệu API công khai chỉ bị giới hạn sử dụng đối với bất kỳ đối tượng nào khác ngoài nhà phát triển. Tài liệu cho những người sau đây - họ sẽ cảm ơn bạn.

Answer 2

Tôi sẽ không làm như vậy. Nếu các phương pháp riêng của bạn cần tài liệu, bạn có thể dành thời gian làm cho mã của bạn sạch hơn trong lĩnh vực này.

Chỉnh sửa: ngay cả với bản tóm tắt, tôi sẽ không ghi lại tài liệu. Phương pháp riêng có thể thay đổi, nảy mầm lại, biến mất. Một trong những nguyên lý cơ bản của OO là một trong những đóng gói. Bạn không cần biết phương thức riêng tư đang làm gì. Và đối với các nhà phát triển, ai sẽ cập nhật tất cả tài liệu này? Lần đầu tiên bạn nhưng trong tương lai?

Chỉnh sửa 2: Từ ý kiến ​​

tôi phản đối kịch liệt. Thời gian duy nhất một phương pháp riêng tư không được ghi chép (theo một cách nào đó) là khi mục đích của nó là hoàn toàn rõ ràng từ tên của nó và mã nguồn của nó. Nếu có bất cứ điều gì "thông minh" về mã của bạn ở tất cả, nó xứng đáng một bình luận giải thích lý do tại sao bạn đang làm theo cách đó.

Tôi hoàn toàn đồng ý nhưng .. mã không nên 'minh', mã nên chức năng và có thể đọc được. Hầu hết thời gian bạn nên nhắm đến mã của bạn càng rõ ràng càng tốt cho người đọc, nếu bạn cần bình luận nó, thì bạn nên xem xét làm cho mã của bạn rõ ràng hơn trước khi bạn nhấn javadoc (hoặc bất kỳ thứ gì bạn sử dụng).

Chỉnh sửa 3:

Bạn sẽ thấy gì hơn?

/** 
* This method doesn't do what you expect it to. 
* Below you will find a whole ream of impenetrable 
* code. Where there are bits that look that they do x, they don't 
* they do y. 
**/ 
private void someComplexInternalMethod() 
{ 
    ... 
    badly named variables 
    comments to describe intent 
    perhaps some out of date orphaned comments 
    as code has been removed but comment remains 

    .... 
    .... 
    looong methods 
} 

private void WellNamedMethod() 
{ 
    ... 
    well named variables 
    shorter method, highly cohesive 
    self documenting 
} 

Answer 3

Chắc chắn là vậy. Trong bất cứ điều gì nhưng phần mềm tầm thường, bạn có thể làm cho nó nhanh hơn để hiểu mã với việc sử dụng thích hợp các ý kiến, ngay cả đối với tác giả ban đầu một vài tháng sau đó.

Answer 4

Có, chắc chắn. Trong sáu tháng, bạn có thể cần phải quay lại và thực hiện một số bảo trì. Một vài ý kiến ​​được đặt tốt có thể giúp bạn tiết kiệm rất nhiều thời gian và công sức. Bạn có thể không cần phải ghi lại nó trong phạm vi bạn sẽ là một API công cộng nhưng một vài bình luận không bao giờ bị tổn thương.

Answer 5

Khi bạn truy cập các phương pháp riêng tư của mình 6 tháng kể từ bây giờ, chúng sẽ có ý nghĩa với bạn nhiều như bây giờ không? Bạn sẽ cần phải dành nhiều giờ cố gắng để theo dõi các mối quan hệ giữa các thành phần?

Theo kinh nghiệm của tôi, tài liệu hay không bao giờ lãng phí thời gian.

Answer 6

Có, cần phải ghi lại các phương pháp riêng tư của bạn. Nó ngày càng trở nên cần thiết khi nhiều nhà phát triển đang sử dụng mã của bạn và đang sửa đổi mã của bạn. Phương pháp riêng tư guarente một chức năng cụ thể giống như phương pháp công cộng. Sự khác biệt là cách mã được sử dụng. Tài liệu của các phương thức riêng sẽ đẩy nhanh việc tái cấu trúc xuống dòng.

Answer 7

Vâng, mã đó cũng nên được duy trì, bạn có nghĩ vậy không?Tất nhiên họ nên được ghi lại! Bạn sẽ phải xem xét mã đó trong một vài tháng và bạn sẽ muốn có một cái gì đó để tham khảo khi thực hiện một thay đổi.

Answer 8

Có, có, có. Viết bất kỳ mã nào bạn viết.

Cuối cùng, một người nào đó sẽ duy trì mã mà bạn viết. Tài liệu là một cách để bạn có thể giúp họ hiểu được suy nghĩ của bạn khi viết đoạn mã cụ thể đó. Các hàm riêng tư đặc biệt quan trọng đối với tài liệu vì chúng có xu hướng có lượng sử dụng ít nhất trong mã của bạn mà từ đó một nhà phát triển có thể suy ra các bất biến của họ.

Answer 9

Ghi lại phương pháp công khai rất hữu ích cho cả người bảo trì và những người sử dụng gói của bạn.

Ghi lại phương pháp riêng tư hữu ích cho người bảo trì hoặc gói của bạn (bao gồm cả bạn).

Tóm lại, nó cần thiết theo một cách hơi khác. Ví dụ, việc ghi lại các phương thức riêng tư không cần phải chính thức.

Answer 10

Bạn nên cấu trúc lại mã của mình để rõ ràng để tài liệu triển khai không cần thiết.

Không sử dụng khả năng nhận xét mã của bạn để cho phép bạn lười biếng trong việc viết mã hiển nhiên ngay từ đầu.

Tài liệu cho biết điều tương tự mã của bạn nói nhưng bằng ngôn ngữ khác thì không cần thiết. Và giống như mã dự phòng, dự phòng này cũng phải được duy trì, nhưng thường thì không.

Answer 11

Nếu tên phương pháp của bạn không làm cho mục đích của chúng hiển nhiên ngay lập tức thì chúng không được đặt tên tốt. Dựa vào tài liệu về các lớp học có tên là & các phương pháp sẽ luôn quay trở lại để cắn bạn. Tất cả phải mất là một vài trường hợp của những người quên cập nhật các tài liệu và bạn kết thúc với một mớ hỗn độn khủng khiếp. dụ:

BAD

private void Update(string sValue, DateTime dValue) 
{...} 

TỐT HƠN

private void UpdateEmployeeInformation(string jobTitle, DateTime hireDate) 
{...} 

gì về phiên bản thứ hai cần tài liệu? Tên xác định mục đích của nó là gì và các tên param làm cho nó rõ ràng những gì được dự kiến ​​sẽ được thông qua.

Nếu phương pháp của bạn quá dài và phức tạp đến nỗi chúng cần một cuốn tiểu thuyết để giải thích, bạn cần chia nhỏ chúng thành các bit chức năng hợp lý có thể được đặt tên và tập trung cao. Điều đó, IMHO, dễ hiểu hơn nhiều so với một số tài liệu nội tuyến kém được viết có thể hoặc không cập nhật - Tôi sẽ đọc qua tất cả mã để đảm bảo nó phù hợp với những gì tài liệu nói rằng nó nên làm và trong hầu hết các trường hợp, tôi sẽ giả định rằng tài liệu không được duy trì và bỏ qua nó.

Bạn cũng nên có các bài kiểm tra đơn vị làm mã linh hoạt và làm cho chức năng trở nên rõ ràng hơn. Với các lớp học, phương pháp và bài kiểm tra đơn vị được đặt tên tốt, tài liệu bổ sung phục vụ mục đích gì?

Answer 12

Bất kỳ phương pháp nào thực hiện điều gì đó phức tạp, đủ để vừa thú vị vừa không rõ ràng đều đáng để bạn làm rõ bằng một số tài liệu.

Answer 13

Có.Như trò đùa này tôi đã nghe:

Lập trình cũng giống như giới tính. Một sai lầm và bạn phải hỗ trợ nó cho phần còn lại của cuộc đời bạn.

Answer 14

Tuyệt đối. Luôn viết mã với giả định rằng bạn sẽ được yêu cầu sửa đổi hai năm sau đó. Tóm tắt phương pháp là quan trọng nhất của tất cả. Tôi không thể nói với bạn bao nhiêu lần tôi đã bắt lỗi vì tôi đã viết tài liệu (tóm tắt, tranh luận, trở lại) và nhận ra tôi đã bỏ lỡ một cái gì đó.

Answer 15

Đối với giao diện công cộng (ví dụ: phương thức công khai và lớp học), hãy ghi lại mục đích của từng phương pháp - bạn muốn mô tả giao diện công khai của mình (nghĩa là hợp đồng mã) càng rõ ràng càng tốt.

Đối với thành viên riêng tư (nơi bạn thực sự sẽ thực hiện công việc), bạn có thể muốn ghi lại mục đích của các phương pháp. Nhưng sẽ hữu ích hơn khi ghi lại các thuật toán của bạn - tại sao và như thế nào, không chỉ mô tả mã.

Bất kỳ nhà phát triển nào trong tương lai có quyền truy cập vào các thành viên riêng tư của bạn cũng sẽ có quyền truy cập vào mã của bạn. Nếu tôi có thể đọc mã của bạn, tôi có thể tìm hiểu xem nó đang làm gì. Nhưng trừ khi tôi có thể đọc được suy nghĩ của bạn, không có cách nào tôi có thể tìm ra lý do tại sao mã của bạn thực hiện những gì nó đang thực hiện - trừ khi bạn viết một số tài liệu giải thích cho tôi.

Answer 16

Chỉ khi bạn không có gì tốt hơn để làm. Do đó - có thể - không.

Answer 17

Tôi sẽ lấy lập trường không được ưa chuộng và nói không.

Nhiều phương pháp riêng tư của tôi sẽ là các câu lệnh phức tạp trong một phương thức, các câu lệnh yêu cầu nhận xét. Một nửa lý do làm cho chúng một phương pháp riêng là làm rõ mã và giảm nhu cầu ghi lại những gì nó làm.

Tài liệu cần được duy trì & được cập nhật bất cứ khi nào mã thay đổi. Bây giờ bạn đang yêu cầu một nhà phát triển bảo trì thực hiện cùng một công việc hai lần. Một lần để sửa lỗi, và một lần để giải thích sửa chữa.

Theo kinh nghiệm của tôi, hành động thứ hai thường không xảy ra. Tôi đã thừa kế một cơ sở mã 5 tuổi khi tôi bắt đầu ở đây. Trong một ứng dụng cụ thể, khoảng một nửa của tất cả mọi thứ đã được bình luận, thường xuyên - RẤT thường - các bình luận mang ít hoặc không giống với mã thực tế. Hoặc dude là trên axit khi ông đã viết cho họ, hoặc ông đã viết các ý kiến ​​với việc cắt mã đầu tiên, sau đó mã thay đổi và các ý kiến ​​không.

Bây giờ tôi rút ra khá nhiều nhận xét của anh ấy mà không cần đọc chúng. Mỗi ứng dụng hoặc mô-đun lôgic trong một ứng dụng lớn có tài liệu 1 hoặc 2 trang phác thảo mục đích chung, cấu trúc chung và bất kỳ thứ gì không bình thường.

Chúng tôi hy vọng nhà phát triển có thể viết mã có thể đọc được và người mới thuê có thể đọc được mã có thể đọc được.

Bây giờ, hãy để bỏ phiếu xuống bắt đầu!

Answer 18

(chống lại sự đồng thuận) Tôi nhấn mạnh mã tự viết (công khai mặc dù riêng tư). Điều này có thể rất hiệu quả, bạn sẽ cần phải chính thức tài liệu ít hơn nhiều. Một số người thực sự không thích điều này (đôi khi vì lý do tốt). Vì bạn đang đề cập đến việc triển khai riêng tư, các ràng buộc của bạn để đổi tên và sửa đổi theo thời gian ít hơn nhiều. Một giao diện với một số ít các trường hợp đặc biệt là một công thức cho sự thất bại (nhưng chúng vẫn được tạo ra).

Tài liệu: Nếu nó sẽ tiêu thụ phần lớn tiêu đề, nó sẽ có ý nghĩa hơn.

Tôi có thói quen chia sẻ tài liệu xấu/vô nghĩa vì, như giao diện, không có gì tốt hơn xấu. hehe

Answer 19

Cá nhân tôi tin vào mã tự viết nhiều hơn trong tài liệu mã. Việc sử dụng nhiều chức năng tiết lộ ý định, các chức năng không có tác dụng phụ, vv ..

Nhưng đôi khi không thể để mã tự tài liệu, và trong trường hợp đó, tôi sẽ luôn ghi lại các chức năng, hoặc các hoạt động bên trong.

Answer 20

Những ngày này tôi thường viết tài liệu cấp lớp/phương thức trước khi bắt đầu trên mã. Điều này đặc biệt hữu ích trong việc giữ cho các lớp được xác định rõ ràng và các phương thức một mục đích, bởi vì bạn có một lời nhắc ngay trước mặt bạn sẽ cho bạn biết khi nào lớp/phương pháp của bạn đã phát triển ngoài ý định ban đầu của bạn.

Tôi không thích viết tài liệu nhiều hơn bất kỳ ai khác có thể viết mã, tuy nhiên tôi không thấy rằng nó ăn mã hóa/gỡ lỗi thời gian, vì hành động giải thích cho chính mình những gì bạn định làm là tất cả về cải thiện đầu ra từ thời gian suy nghĩ của bạn.

Nhận xét phương pháp cũng cung cấp kiểm tra kép hữu ích, bởi vì nếu mã không làm những gì nhận xét cho biết, thì đó là điều đáng xem xét khi gỡ lỗi.

Từ góc độ của trình đọc mã, vì mã hữu ích sẽ được đọc nhiều (hàng trăm nghìn lần) so với mã được viết, các nhận xét ghi lại hợp đồng mã lưu người đọc không phải tìm ra mã nào tiếp theo Mức độ chi tiết. Khi bạn đọc lướt qua hàng nghìn dòng mã, công cụ này sẽ tiết kiệm được những công tắc ngữ cảnh tâm lý đắt tiền từ đọc lướt qua đến phân tích và ngược lại.

Những người dành phần lớn ngày làm việc của mình đọc số lượng lớn mã là các nhà lãnh đạo nhóm và kiến ​​trúc sư chịu trách nhiệm giữ cho hệ thống hoạt động và thương lượng với quản lý thay mặt cho nhóm phát triển của họ. Ngay cả mã được viết cũng khó đọc nhanh và về số lượng, bởi vì phần lớn nó sẽ ở mức trừu tượng khác với mức mà người đọc quan tâm.

Nếu những người đại diện cho các nhóm phát triển có thể ' Đọc mã nhanh chóng, thật khó để có các cuộc thảo luận dựa trên bằng chứng với các nhà quản lý, và các quyết định được đưa ra mà không bị ảnh hưởng bởi thực tế kỹ thuật.

Lặp lại nhiều lần, điều này dẫn đến các vấn đề khó khăn cho nhóm phát triển, điều này có thể tránh được bằng cách áp dụng một chút kỷ luật kỹ thuật ở cấp độ chi tiết.

Không phải tất cả các hệ thống đều lớn, phức tạp và ngắn về rất kinh nghiệm, những người chỉ biết câu trả lời, nhưng một số hệ thống giống như vậy, và họ có thể đột nhiên nhận được điều đó. Thế hệ tiếp theo của rất kinh nghiệm trong đào tạo sẽ cảm ơn bạn đã ghi lại mã của bạn.

Answer 21

Còn trường riêng thì sao? Đối với một lớp có thể nối tiếp các trường riêng tư phải được ghi thành tài liệu. Từ "Java hiệu quả" của Johsua Bloch:

Trường riêng xác định API công khai, là biểu mẫu tuần tự hóa và API công khai này phải được ghi lại.Sự hiện diện của thẻ @serial kể tiện ích Javadoc để đặt tài liệu này trên một trang đặc biệt mà tài liệu dạng serialized