Có bất kỳ lý do hợp lý để tự động tạo tài liệu mã? [đóng cửa]


60

Tạo tài liệu tự động có thể được thực hiện với nhiều công cụ khác nhau, GhostDoc là một trong những công cụ nổi bật hơn. Tuy nhiên, theo định nghĩa, mọi thứ nó tạo ra đều dư thừa. Nó xem xét tên của các phương thức, các lớp, v.v. và xuất ra tiếng Anh có thể giải thích chúng rõ ràng hơn. Trong trường hợp tốt nhất, nó thực hiện những gì người đọc có thể đã làm trong đầu của họ (ví dụ được lấy từ đây ):

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

Trong điều tồi tệ nhất, nó thực sự có thể tạo ra tài liệu kỳ quái thực sự gây hiểu lầm trong nỗ lực của mình để tìm ra ý nghĩa của các tên:

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

Có vẻ như thái độ với GhostDoc là, "về bản chất là tốt hơn để có một loại tài liệu XML chính thức", nhưng khi tài liệu đó dư thừa 100%, tại sao? Không phải nó chỉ lãng phí một tấn không gian tốt nhất sao?

Tại nơi làm việc của tôi, chúng tôi phải ghi lại tất cả mọi thứ và hầu như luôn luôn với các tài liệu được tạo tự động của GhostDoc. Bạn có làm điều này không, và có bất kỳ lý do hợp lý nào không chỉ đơn giản là để lại mã không có giấy tờ nếu bạn không thực sự tự viết tài liệu?



5
Nếu bạn sử dụng lại DLL của mình và muốn giữ gợi ý IntelliSense về phương thức và tham số nào, thì bạn cần phải có nhận xét về mỗi lớp, phương thức và tham số. Nếu không, dự án sẽ nổ tung và XML sẽ không được tạo. Tôi thấy việc sử dụng các bình luận được tạo tự động như thế là một cách tiếp cận lười biếng một cách lố bịch để làm điều đó.
krillgar

11
Nó làm cho tài liệu không cần thiết để các nhà phát triển cảm thấy khó chịu với nó và điền vào tài liệu chính xác. Tâm trí trò chơi ở khắp mọi nơi.
Kroltan

2
đôi khi bạn có thể cung cấp tài liệu nhưng không phải mã
Leo

2
Câu trả lời ngắn: Không
Thomas Eding

Câu trả lời:


14

[...] ghi lại mọi thứ và hầu như luôn luôn với các tài liệu được tạo tự động của GhostDoc. Bạn có làm điều này không, và có bất kỳ lý do hợp lý nào không chỉ đơn giản là để lại mã không có giấy tờ nếu bạn không thực sự tự viết tài liệu?

Không. Tài liệu được tạo bởi GhostDoc là mẫu soạn sẵn (tương tự như cách tạo một lớp OO mới trong IDE tạo ra bảng chữ cái cho một lớp với hàm tạo hoặc một cái gì đó). Phần hữu ích của tài liệu là những gì sẽ theo sau khi thêm bản tóm tắt.

Trong khi bạn phải ghi lại tất cả mọi thứ tại nơi làm việc của bạn, có vẻ như các đồng nghiệp của bạn đã tìm thấy cách hoàn hảo xung quanh nó: chỉ giả vờ.


-1. Chỉ giả vờ? Điều đó có thể làm việc tuyệt vời cho một dự án một người sẽ không bao giờ được sử dụng lại. Một số mức độ tài liệu / bình luận là cần thiết ngay cả với một dự án một người nếu độ phức tạp của nó lớn hơn "thế giới xin chào" và nếu bạn có kế hoạch chọn dự án đó trong sáu tháng. Trong một dự án liên quan đến hàng chục hoặc thậm chí hàng trăm người, việc không ghi chép / nhận xét có thể giết chết dự án.
David Hammen

14
@DavidHammen, tôi nhận thức rõ rằng một dự án có thể chết do không đủ tài liệu. Ngoài ra, "chỉ là giả vờ" không phải là một lời khuyên cho OP, mà là một sự chỉ trích các đồng nghiệp của OP.
utnapistim

73

Trong một ngôn ngữ được gõ tĩnh, tài liệu kiểu Javadoc không dành cho các tác giả, nó dành cho người tiêu dùng. Tự động tạo đơn giản giúp các tác giả dễ dàng duy trì tài liệu cho người khác tiêu thụ hơn.

Nếu bạn đang sử dụng ngôn ngữ được nhập tĩnh và không viết thư viện cho tiêu dùng của bên thứ ba, tính năng tự động không mua cho bạn nhiều và theo kinh nghiệm của tôi hiếm khi được sử dụng. Nếu bạn đang sử dụng ngôn ngữ được nhập động, tài liệu kiểu javadoc thường được sử dụng để ghi lại các loại, ngay cả khi chỉ sử dụng nội bộ, nhưng tự động không biết các loại, vì vậy tất cả những gì giúp bạn tiết kiệm là tránh sao chép thủ công.

Dù bằng cách nào, đừng nghĩ tự phát như là sản xuất một sản phẩm hoàn chỉnh. Hãy nghĩ về nó như là sản xuất nồi hơi cho bạn, vì vậy bất kỳ thay đổi nào bạn thực hiện thủ công đều có ý nghĩa.


26

Có bất kỳ lý do hợp lý để tự động tạo tài liệu mã?

Từ quan điểm của ai?

Nếu tôi đang điều hành công ty hoặc nhóm nhà phát triển, thì không có lý do chính đáng. Tôi kiên quyết trong trại "bình luận nên giải thích tại sao ". Buộc mọi người bình luận các lớp / chức năng / thuộc tính tồi tệ hơn là vô giá trị, vì họ đã hết thời, họ đánh lừa người đọc, họ được sử dụng như một cái cớ để không tạo ra mã có thể đọc được, v.v. Những bình luận này làm lãng phí thời gian cả việc viết chúng, đọc mã và các lỗi do chúng gây ra. Một số người sẽ cho rằng các tài liệu API kiểu JavaDoc là một lý do để bình luận, nhưng ngay cả trong lập luận đó, một phần nhỏ mã của bạn phải là một phần của API công khai và JavaDoc không phải là một thay thế cho các tài liệu API thực tế.

Là một nhà phát triển, tôi đã làm việc ở một vài nơi yêu cầu bình luận ở những nơi này, bất chấp ý kiến ​​của tôi. Vì tôi không có thời gian hay kiên nhẫn để viết một đống tào lao mà không ai sẽ sử dụng, nên tôi thay vào đó là GhostDoc. Điều này cho phép tôi dành thời gian đó thực sự làm những việc quan trọng. Hiệu quả hơn nhiều so với thay đổi chính sách của công ty.

Một điều tốt khác mà tôi đã tìm thấy khi sử dụng GhostDoc là nó phục vụ như một kiểm tra xem tên của tôi có tốt không. Nếu GhostDoc không thể tạo tài liệu phù hợp cho một chức năng, thì đó là mùi mà tên chức năng hoặc tham số của tôi có thể kém. Trong khi tôi sẽ không sử dụng các công cụ để chỉ này, đó là một hiệu ứng nhỏ bên tốt đẹp nếu tôi đang được thực hiện để lãng phí thời gian của tôi anyways.


1
Ngoại trừ ví dụ của tôi cho thấy GhostDoc có thể không tạo được tài liệu phong nha ngay cả khi tên đó không thực sự tệ đến vậy.
Jez

11
Có, một số người quản lý phải tuyên bố "chúng tôi ghi lại tất cả mã của chúng tôi" và một số người quản lý khác nghĩ rằng mọi thứ đều tuyệt vời. Những người không hiểu biết vẫn ở đó, nhưng họ vẫn hạnh phúc.
JeffO

3
@jez - Chắc chắn, đó chỉ là một mùi. Đôi khi nó đúng, đôi khi không.
Telastyn

1
Trả lời bằng một câu hỏi. Nice;)
Pierre Arlaud

@Jez Bạn nói cái tên đó không tệ lắm. Tuy nhiên, RichTextSelection_Changedphương thức thể dễ sử dụng hơn nếu nó thuộc về một đối tượng lựa chọn và nếu nó không được đặt tên theo loại tham số của nó. Mặc dù như Telastyn đã nói, nó chỉ là một mùi, có thể đúng hoặc sai đối với thiết kế của bạn và các đề xuất của tôi có thể sẽ không cải thiện sản lượng GhostDoc.
dcorking

21

EDIT : Tôi đã hiểu nhầm câu hỏi ban đầu; mặc dù tôi nghĩ rằng tạo ra tài liệu (tức là không mã hóa tài liệu ) có thể cực kỳ có giá trị (xem câu trả lời ban đầu liên quan đến Doxygen dưới đây), tự động tạo ra ý kiến (mà là cái gì đó thực sự làm GhostDoc) nghe có vẻ điên rồ đối với tôi. Tôi không thể hiểu tại sao mọi người mong đợi một chương trình có thể đọc mã nguồn chưa được bình luận và viết bình luận sẽ thực sự làm rõ nó.

Tôi có thể hiểu được rằng một tiện ích tạo bình luận cực kỳ "thông minh" có thể được lập trình để nhận ra các mẫu nhất định và tạo ra các nhận xét kiểu "cách"; chẳng hạn, nó có thể nhận ra thuật toán tính toán phương sai của Knuth và đưa ra nhận xét giải thích cách thức hoạt động của nó và tại sao thuật toán ngây thơ sẽ không phù hợp. Có lẽ một tiện ích như vậy thậm chí có thể được lập trình để nhận ra các mẫu thiết kế hướng đối tượng chính tắc (ví dụ: Tóm tắt Factory) và chèn các bình luận cho biết mẫu nào đang được sử dụng và các lớp nào đang đóng vai trò gì.

Nhưng theo tôi, các bình luận hữu ích nhất không giải thích "cách thức" một cái gì đó hoạt động, vì chính mã sẽ hiển thị điều này, nhưng các bình luận " tại sao ", giải thích "tại sao" một điều cụ thể đang được thực hiện. Như David Hammen đã lưu ý trong các bình luận bên dưới, để tạo ra các bình luận "tại sao", một tiện ích sẽ cần phải "đọc suy nghĩ của lập trình viên". Rõ ràng điều này là không thể.

Tuy nhiên, dựa trên các ví dụ đã cho, có vẻ như GhostDoc thậm chí không hoàn thành nhiệm vụ tạo ra các bình luận kiểu "đúng". Vì vậy, nó là, theo ý kiến của tôi, tồi tệ hơn vô dụng, vì những gì nó không tạo ra có thể ngớ ngẩn và gây hiểu lầm (như trong ví dụ thứ hai).


Câu trả lời gốc: tại sao trích xuất và định dạng tài liệu tự động là một ý tưởng tốt

Nhóm phần mềm của tôi sử dụng Doxygen. Lý do chính cho điều này là vì chúng tôi cần tài liệu không phải mã nguồn (tức là người không phải lập trình viên có thể đọc được) về các tính năng / hành vi / v.v., nhưng chúng tôi cảm thấy rằng nên tích hợp mã này vào chính mã nguồn hơn là duy trì nó như một tài liệu thứ hai . Điều này giúp chúng tôi giữ tài liệu đồng bộ với mã nguồn (mặc dù tất nhiên không bao giờ được đảm bảo hoàn toàn, ít tự động hơn) và giảm thiểu chi phí tài liệu bằng văn bản (vì tài liệu cho một đoạn mã có thể được kết hợp một cách tầm thường vào tập tin chứa mã chính nó).

Vì vậy, trọng tâm của việc sử dụng Doxygen của chúng tôi không phải là trích xuất thông tin từ chính mã, mà là giữ tài liệu về mã nguồn càng gần càng tốt với chính mã nguồn.

Điều này cũng cho phép chúng tôi sử dụng một công cụ duy nhất để tạo cả "lý thuyết hoạt động" mô tả toàn bộ cơ sở mã của chúng tôi và một số "ghi chú phát hành" mô tả sản phẩm phần mềm nhưng thực tế không chứa bất kỳ "tài liệu mã" thực tế nào trong ý nghĩa điển hình.

Về lý do tại sao chúng tôi sẽ cần tài liệu phi mã nguồn về hành vi của mã của chúng tôi, có hai lý do:

  • Sản phẩm của chúng tôi không chỉ đơn thuần là phần mềm; nó là một công cụ phức tạp tích hợp nhiều thành phần phần cứng, bao gồm một số laser và chất lỏng ưa thích. Chúng tôi cần các kỹ sư không có nhiều nền tảng phần mềm để hiểu chính xác cách thức bên trong mã của chúng tôi hoạt động và bảo họ "đọc mã nguồn" sẽ không thực hiện được điều này.
  • Chúng tôi phải tuân theo khá nhiều quy định chất lượng, một số quy định nội bộ của công ty và những người khác được ủy quyền hợp pháp bởi chính phủ liên bang. Mặc dù quy trình chất lượng là (hoặc ít nhất có thể) cực kỳ có giá trị và hữu ích, nhưng nó liên quan đến một lượng chi phí không đáng kể, một phần trong đó là nhiệm vụ của nhóm phần mềm để cung cấp loại tài liệu chi tiết này của phần mềm. Một lần nữa, việc tích hợp tài liệu này với chính mã giảm thiểu chi phí và giúp chúng tôi cập nhật tài liệu.

Lưu ý rằng dấu đầu dòng thứ hai khá giống với điểm mà một vài câu trả lời khác đã đưa ra về các nhà quản lý muốn đảm bảo (/ quyền khoe khoang) khi biết rằng một số tài liệu (bất kể chất lượng) tồn tại cho mọi đoạn mã nguồn; cách đóng khung đó, tuy nhiên, bỏ qua thực tế là tài liệu được ủy quyền bên ngoài thực sự có thể có một số lợi thế hợp pháp.


Doxygen có xuất ra tiếng Anh không, hay nó chỉ định dạng các chuỗi doc đã được viết bằng tiếng Anh?
dcorking

3
@dcorking Cái sau, mặc dù nó cũng cố gắng sắp xếp mọi thứ theo cấu trúc tĩnh của mã và cung cấp các siêu liên kết tự động ở mọi nơi có thể (và những điều này thường bị sai).
Kyle Strand

2
Thật ra, đó là cả hai. doxygen phân tích mã và các bình luận doxygen. Tên lớp, tên lớp cha, tên thành viên dữ liệu, tên hàm, kiểu đối số và tên, kiểu trả về: Tất cả đều đến từ mã được phân tích cú pháp. Những điều đó có nghĩa là gì từ các bình luận doxygen. Doxygen phàn nàn nếu một mục được chỉ định là \ param trong nhận xét doxygen không phải là đối số và có thể được đưa ra để khiếu nại về các mục không có giấy tờ. Khác với những kiểm tra tối thiểu này, vấn đề bình luận và không khớp mã vẫn là một khả năng. Điều đó nói rằng, tôi yêu doxygen. Nó tốt hơn nhiều so với viết API bằng tay.
David Hammen

@DavidHammen, Doxygen có tạo ra các câu như "Làm phong phú lựa chọn văn bản không?"? (Tôi đã không sử dụng nó trong nhiều năm và những phiên bản đầu tiên đó không tạo ra tiếng Anh mà tôi nhớ lại.)
dcorking

@dcorking _ Tôi không biết ý nghĩa của bạn là gì. Doxygen không thể đọc được suy nghĩ của lập trình viên. Để có một ví dụ tốt về những gì doxygen có thể làm, hãy xem trang cấp cao nhất này cho Eigen , một gói tính toán khoa học C ++ khá phổ biến. Chọc xung quanh! Bạn có thể thấy một số tài liệu rõ ràng được viết bởi con người, tài liệu khác hoàn toàn được tạo tự động, nhưng tài liệu khác là sự pha trộn giữa người viết và tự động tạo. Nếu được nói với, doxygen sẽ tự động tạo ra fan-in (người tham chiếu chức năng này) và fan-out (chức năng này gọi là gì).
David Hammen

7

Chắc chắn, tài liệu tự động đặc biệt hữu ích khi nó có thể tái tạo các mô tả phù hợp, sâu sắc được viết bởi các tác giả mã. Mặt khác, nó chỉ là một định dạng tự động được tôn vinh.

Nhưng định dạng không phải là vô dụng. Có giá trị trong việc có thể tìm thấy các phương thức công khai của một thành phần lớn trong một cái nhìn, được sắp xếp và đảm bảo hoàn thành. Nếu bạn cần một trình frobnickbiến đổi và nó không ở đó, bạn sẽ biết nó không ở đó mà không lội qua mã nguồn. (Kết quả tiêu cực cũng có giá trị: bạn biết bạn phải làm điều gì đó và bạn có nhiều thời gian hơn để làm điều đó vì bạn không phải lội nước.)

Vì vậy, có, tạo tài liệu tự động thêm một số giá trị. Chắc chắn là không nhiều như các nhà quản lý có thể giả định, và thường thậm chí không nhiều như một trình soạn thảo sao chép thực sự tốt, nhưng không phải là không có gì.


4
Tôi không hiểu nhận xét của bạn về "lội qua mã nguồn". Chắc chắn trong cả hai trường hợp, bạn sẽ tìm kiếm một cái gì đó như 'frobnick mutator' hoặc 'frobnickmutator' ... tài liệu được tạo tự động giúp như thế nào?
Jez

2
@Jez Không phải ai cần biết về trình frobnickbiến đổi sẽ là một nhà phát triển phần mềm; họ có thể không hiểu cách xem qua mã nguồn (có thể yêu cầu làm quen với grep/ cscope/ ack/ etc) và ngay cả khi họ tìm đúng tệp, thì họ có thể không tìm thấy mã nguồn thực tế dễ đọc ngay cả khi nó được nhận xét tốt từ góc độ SW. Khả năng xem qua một chỉ mục hoặc nhập vào một thanh tìm kiếm, sau đó duyệt qua văn bản trông giống như một phần của trang web, có thể khá có giá trị.
Kyle Strand

4
@Jez, Một tài liệu dễ đọc của con người cho những người không lập trình hoặc ít nhất là những người không phải là chuyên gia không thừa. Nó là bắt buộc. Để thể hiện rõ ràng những gì mã dự định làm. Nó phải được ghi lại trước khi bất kỳ mã nào được viết. Và cập nhật khi kiến ​​thức về (các) vấn đề và giải pháp phát triển. Các ví dụ được trích dẫn là không đáng để giữ, nhưng 'tất cả trong mã nguồn' là ném em bé bằng nước tắm. "Tạo tự động" nghe có vẻ tệ, "không có tài liệu, chỉ cần đọc nguồn" còn tệ hơn. Giống như khi bạn hỏi ai đó, "Cái đó làm gì?" và họ nói, "Hmm, hãy chạy nó và tìm hiểu!"
Hóa đơn IV

6

Ở dạng này, nó tệ hơn vô dụng nhưng chỉ vì nó chỉ dựa vào chữ ký công khai (mà trong trường hợp của Javadoc, dù sao thì ai cũng có thể nhìn thấy tài liệu API).

Nhưng có thể viết các công cụ tài liệu tự động cũng xem xét phần thân của phương thức. Để chứng minh khái niệm, tôi đã viết một plugin Eclipse nhỏ khập khiễng thêm một danh sách các phương thức khác được gọi từ phương thức được ghi lại vào Javadoc. (Tất nhiên, không phải mọi cuộc gọi, bạn đều có thể xác định bộ lọc, theo gói.)

Và tôi thực sự đã thấy nó khá tiện dụng khi tinh thần vạch ra một cơ sở mã hoàn toàn xa lạ. Cấp, đó là một trường hợp sử dụng rất hạn chế nhưng nó chắc chắn là một trợ giúp.

Dựa trên kinh nghiệm đó, câu trả lời cho câu hỏi là: có, nhưng chúng ta cần các công cụ thông minh hơn nhiều.

Cập nhật: Tất nhiên một câu hỏi bổ sung (một câu hỏi nên được hỏi trước khi viết bất kỳ loại tài liệu nào) là đối tượng mục tiêu là ai. Nếu chúng tôi ghi lại một API công khai cho các máy khách của API đó, việc thêm tất cả chi tiết triển khai này là một điều không nên vì mọi thứ bạn đặt trong Javadoc về mặt kỹ thuật là một phần của API.

Nhưng nếu đối tượng mục tiêu là các nhà phát triển khác làm việc trên cùng một sản phẩm, việc tự động thêm thông tin về chi tiết triển khai, chẳng hạn như phương pháp nào sửa đổi hoặc đọc một trường nhất định đều có thể chấp nhận được và khá hữu ích.


6

Tôi không biết về các môi trường khác nhưng khi nói đến các dự án PHP lớn (thường là nguồn mở) mà người khác đã viết, phpXRef là một trình bảo vệ cuộc sống tuyệt đối (đặc biệt là nếu tài liệu được đặt trực tuyến và Google có thể lập chỉ mục cho nó).

Ngay cả một dự án được bình luận xấu ít nhất cũng có thể giúp tôi theo dõi nơi mọi thứ đã được xác định và nơi chúng được sử dụng (ví dụ khi tái cấu trúc).

Khi được bình luận tốt, các trang kết quả hình thành gần với một cuốn Kinh thánh hoàn hảo cho codebase (dù sao tôi cũng sử dụng).

Hơn nữa, IDE ưa thích của tôi sẽ tự động tạo khối nhận xét (nếu tôi nhập / **), công việc này chiếm khoảng 75% công việc bình luận cho tôi. Thật đáng kinh ngạc khi có bao nhiêu điều ngu ngốc mà tôi đã dừng lại trong suốt cuộc đời lập trình viên của mình chỉ vì tôi phải giải thích cho những người khác (và cả tôi trong tương lai) những gì tôi đang làm. Khi nhận xét của tôi về trình tạo tài liệu lớn hơn phương thức, điều này thường có nghĩa là tôi chưa uống đủ cà phê và có thể muốn suy nghĩ kỹ hơn một chút.

Các khối nhận xét giống nhau đó cũng tạo ra văn bản "trợ giúp" hoàn thành nội tuyến để tôi có thể thấy chính xác những gì được mong đợi (bởi các lập trình viên khác) khi tôi đang viết lệnh gọi hàm. Đây là một sự tăng năng suất lớn đối với tôi (đặc biệt là trong những trường hợp hiếm hoi mà một số nhà phát triển hữu ích khác đã viết "vì lợi ích không làm / không làm X" - có thể tiết kiệm rất nhiều nỗi đau.

Tôi không thể nhấn mạnh đủ mức độ hữu ích của các loại đầu vào dự kiến ​​được chỉ định trong các dự án PHP phức tạp (và thường được đặt tên xấu) và thứ tự đối số trong các phương thức ít được sử dụng. Ngay cả với mã của riêng tôi, tôi không thể luôn nhớ những đối số tôi đã chỉ định cho điều gì đó mà tôi chưa từng chạm vào trong thời đại.

Trong một trường hợp, điều đó có nghĩa là nguồn gốc của các vấn đề tái diễn là vì một số lý do phản ánh không tốt đối với các nhà phát triển trước đó, một số hàm và thậm chí các hằng số đã được xác định ở một số lượng lớn (với mức độ không nhất quán để thêm "niềm vui") . Đó là dấu hiệu để đi từ dự án.

Trong các dự án lớn hơn bắt đầu trước khi tôi tham gia, tôi có thể thấy nhà phát triển nào (giả sử họ đã gắn thẻ tệp lớp với tên và email) đã tạo lớp và chỉ cần có thể tìm và nói chuyện với nhà phát triển phù hợp là vô cùng hữu ích.

Danh sách tác vụ tự động - sử dụng thẻ @todo (phổ biến trong loại dự án tôi thấy mình đang làm việc) có nghĩa là tài liệu có thể theo dõi những thứ cần thêm một số công việc (hoặc các tính năng được thừa nhận là thiếu). Một lần nữa, IDE của tôi theo dõi điều này và một mình đóng vai trò là một hướng dẫn tốt về những gì cần sự chú ý của tôi trước tiên.

Cuối cùng (và rất quan trọng đối với tôi), nó loại bỏ chi phí không hề nhỏ trong việc viết ra tất cả những điều đó và sau đó cố gắng cập nhật khi một số (đọc nhiều) lập trình viên cam kết thay đổi và không nói chuyện với những người duy trì tài liệu.

Vì vậy, lý do bao gồm:

  • Tiết kiệm cho các nhà phát triển sau này một đống thời gian,
  • Theo dõi nơi các chức năng được gọi (và được xác định),
  • Phát hiện mã hóa ngớ ngẩn,
  • Tìm kiếm (như người khác đã chỉ ra) khi thiếu thứ gì đó rõ ràng,
  • Đơn giản hóa tái cấu trúc (không bao giờ nhiều niềm vui)
  • (Trong nhiều trường hợp) nhận được ý tưởng về những gì nhà phát triển đã cố gắng thực hiện (giả sử anh ta hoặc cô ta để lại một số ghi chú).
  • Nếu dự án đủ phức tạp để có nhiều giấy phép đang diễn ra (không vui) tôi có thể nhanh chóng xem giấy phép nào áp dụng cho bất kỳ phần nào. Phải thừa nhận rằng đây là phần thưởng phụ.
  • Lấy ý tưởng về người để nói chuyện về một tệp dự án.
  • Danh sách nhiệm vụ tự động

Ngoài ra, đừng đánh giá thấp giá trị của việc giữ cho những ông chủ tóc nhọn vui vẻ khi chạm vào nút.

Nói tóm lại, "bình luận tài liệu tự động" rất quan trọng đối với thói quen mã hóa của tôi. Tôi chắc chắn có nhiều người nghĩ rằng đó là khập khiễng nhưng tôi cũng chắc chắn rằng có một vài người công bằng biết chính xác những gì tôi đang nói. Tôi không biết mình đã sống sót như thế nào trước khi khám phá phpXRef (và IDE yêu thích của tôi).


4

Việc sử dụng các trình tạo tài liệu để tạo ra các bình luận sôi nổi hoặc bình luận "sau đó được sửa đổi bởi các nhà phát triển thực tế là điều tốt. Tôi thường sử dụng hàm tự động JavaDoc của Eclipse để tạo nhận xét tiêu đề với các loại tham số và trả về các giá trị đã được điền vào, sau đó chỉ cần thêm "thịt" của tài liệu.


3

Là một nhà phát triển C #, tôi sử dụng Stylecop, bắt buộc nhận xét cho tất cả các lớp, phương thức, v.v. Tôi tự động tạo các nhận xét này bằng một công cụ. Hầu hết thời gian, các nhận xét được tạo bởi công cụ là đủ và có thể được suy ra theo tên của đối tượng, ví dụ: lớp Person có và trường ID.

Nhưng NẾU tôi muốn bình luận một phương pháp không rõ ràng hơn nữa, rất dễ dàng để mở rộng tài liệu soạn sẵn và một vài lời giải thích về những gì nó làm. Ví dụ: Tôi có một phương thức trên lớp Person, trả về FirstName + Lastname, nhưng tôi đã thêm một chút tài liệu về những gì xảy ra khi thiếu một trong hai.

Tóm lại: Tôi nghĩ rằng tài liệu soạn sẵn có thể gây bất lợi nếu bạn không bao giờ thay đổi văn bản được cung cấp bởi trình tạo. Trong trường hợp đó, nó chỉ là nhiễu đường truyền. Nhưng nếu bạn xem chúng là một mẫu, họ sẽ hạ thấp thanh để cung cấp các nhận xét tốt và hữu ích cho chính bạn hoặc người tiêu dùng của bạn. Bạn có thể viết bình luận mà không tự động tạo chúng? Chắc chắn, nhưng bạn sẽ phải tuân theo định dạng (trong trường hợp C # khá dài dòng và khó chịu khi tạo bằng tay) và điều đó làm giảm cơ hội bạn thực sự cung cấp nhận xét này tại al ..


Tuy nhiên, quy tắc Stylecop có thể bị vô hiệu hóa. Quy tắc SA1600 nếu tôi không nhầm.
Jez

@Jez Có, nhưng tôi đã quyết định chống lại nó. Nó dẫn đến rất nhiều bình luận không cần thiết, nhưng nó cũng khuyến khích tôi viết những bình luận cần thiết. Nó không hoàn hảo, nhưng là gì? Những gì tôi đã vô hiệu hóa là kiểm tra chính tả, dường như thậm chí không biết các từ CNTT cơ bản
Christian Sauer

3

Tránh Tautology

Lần duy nhất bạn cần bất kỳ loại tài liệu nào cho mã là để giải thích tại sao một phương thức / hàm đang làm một cái gì đó, tên sẽ đủ cho những gì nó đang làm.

Nếu bạn đang làm một cái gì đó không phải là thành ngữ, hoặc vi phạm nguyên tắc ít ngạc nhiên nhất thì tài liệu được yêu cầu.

Tài liệu được tạo tự động chỉ là một công cụ định dạng để xuất thông tin gần như được yêu cầu bởi người tiêu dùng mã của bạn. Javadoc làm điều này cực kỳ tốt.

Không phải mọi thứ nên được ghi lại bằng tay

Những thứ như phương thức getXXX / setXXX nên tự giải thích, vì vậy tài liệu tạo tự động chỉ cho bạn biết chúng tồn tại sẽ được đón nhận.


2

Tài liệu mã, ít nhất là loại "tự động", đại diện cho mẫu số ít phổ biến nhất cho những người đang cố gắng hiểu ứng dụng.

Những người dùng tinh vi nhất sẽ không đánh giá cao tài liệu mã tự động. Họ rất muốn có tài liệu "nhắm mục tiêu" cho họ biết những gì (ít) họ cần được nói.

Những người dùng ít tinh vi nhất sẽ không đánh giá cao nó vì lý do ngược lại; dù sao họ cũng sẽ không hiểu.

Những người sử dụng tài liệu mã tự động "đánh giá cao" nhất là những người mà "một chút hiểu biết" là một điều nguy hiểm. "Họ có thể hoặc không thể hiểu tài liệu này (mặc dù họ có khả năng), nhưng họ sẽ cảm thấy tốt về" được giữ trong vòng lặp. "Đối tượng này bao gồm hầu hết các loại" quản lý ". Nếu đó là đối tượng chính của bạn, tài liệu mã tự động có thể là một điều tốt.


0

câu trả lời đơn giản cho "tại sao tạo tài liệu" có thể được trả lời đơn giản bằng cách hiển thị MSDN.

Hãy tưởng tượng bạn đang cố gắng viết một chương trình sử dụng bất kỳ thư viện nào không có tài liệu API. Đó là một cơn ác mộng. MSDN là một ví dụ tuyệt vời về loại tài liệu có thể được tạo từ mã nguồn và nhận xét và tạo thành một tài nguyên thiết yếu cho các nhà phát triển.

Nếu bạn đang viết một ứng dụng (nghĩa là không phải thư viện để người khác sử dụng) thì có thể có trường hợp không bị làm phiền - nhưng ngay cả khi đó, bao nhiêu ứng dụng lớn, chỉ có nội bộ, không chứa nhiều thư viện dù sao? Khi bạn tham gia một nhóm như vậy, việc có một số tài liệu API có thể duyệt sẽ rất hữu ích.

Không có công cụ nào sẽ viết tài liệu của bạn cho bạn, nhưng họ cung cấp cho bạn bản tóm tắt mà dù sao bạn cũng phải viết ra bằng tay, một số công cụ (như doxygen) cũng sẽ tạo sơ đồ và danh sách tham chiếu (ví dụ về chức năng gọi và gọi ) sẽ không dễ dàng được phát hiện ngay cả khi nhìn vào mã nguồn.

Rõ ràng ý thức chung thực dụng nên được áp dụng cho những gì được ghi lại, các thuộc tính và chức năng nhỏ có thể bị bỏ qua (và bị bỏ qua từ thế hệ ngay cả trong các công cụ), nhưng bất cứ lúc nào cũng nên nói "có mã nguồn, đủ tài liệu" bất cứ lúc nào .

Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.