Mã tự viết tài liệu là gì và nó có thể thay thế mã tài liệu tốt không? [đóng cửa]

Tôi có một đồng nghiệp khăng khăng rằng mã của anh ta không cần bình luận, đó là "tự ghi lại."

Tôi đã xem lại mã của anh ấy, và mặc dù nó rõ ràng hơn mã mà tôi đã thấy người khác sản xuất, tôi vẫn không đồng ý rằng mã tự ghi là đầy đủ và hữu ích cũng như mã được nhận xét và mã hóa.

Giúp tôi hiểu quan điểm của anh ấy .

• Mã tài liệu tự là gì
• Nó thực sự có thể thay thế tốt nhận xét và mã tài liệu
• Có tình huống nào tốt hơn mã tài liệu và nhận xét tốt không
• Có những ví dụ mà mã không thể tự ghi lại mà không có ý kiến

Có lẽ đó chỉ là giới hạn của riêng tôi, nhưng tôi không thấy làm thế nào nó có thể là một thực hành tốt.

Đây không phải là một cuộc tranh luận - vui lòng không đưa ra lý do tại sao mã được nhận xét và tài liệu tốt được ưu tiên cao - có nhiều tài nguyên cho thấy điều này, nhưng chúng không thuyết phục được bạn bè của tôi. Tôi tin rằng tôi cần phải hiểu đầy đủ hơn về quan điểm của anh ấy để thuyết phục anh ấy bằng cách khác. Bắt đầu một câu hỏi mới nếu bạn phải, nhưng đừng tranh luận ở đây.

Wow, phản ứng nhanh! Vui lòng đọc tất cả các câu trả lời hiện có và cung cấp nhận xét cho câu trả lời thay vì thêm câu trả lời mới, trừ khi câu trả lời của bạn thực sự khác biệt với mọi câu trả lời khác ở đây.

Ngoài ra, những người bạn đang tranh luận chống lại việc tự viết mã - điều này chủ yếu là để giúp tôi hiểu được viễn cảnh (tức là các khía cạnh tích cực) của các nhà truyền bá mã tự viết tài liệu. Tôi hy vọng những người khác sẽ đánh giá thấp bạn nếu bạn không tiếp tục chủ đề.

Theo tôi, bất kỳ mã nào cũng phải tự ghi lại. Trong mã tốt, tự viết tài liệu, bạn không phải giải thích từng dòng đơn vì mọi mã định danh (biến, phương thức, lớp) có một tên ngữ nghĩa rõ ràng . Có nhiều bình luận hơn mức cần thiết thực sự khiến việc đọc mã trở nên khó khăn hơn (vì vậy), vì vậy nếu đồng nghiệp của bạn

• viết bình luận tài liệu (Doxygen, JavaDoc, bình luận XML, v.v.) cho mọi lớp, thành viên, loại và phương thức VÀ
• nhận xét rõ ràng bất kỳ phần nào của mã không tự ghi tài liệu VÀ
• viết nhận xét cho từng khối mã giải thích ý định hoặc mã thực hiện ở mức độ trừu tượng cao hơn (nghĩa là tìm tất cả các tệp lớn hơn 10 MB thay vì lặp qua tất cả các tệp trong một thư mục, kiểm tra xem kích thước tệp có lớn hơn 10 không MB, lợi nhuận mang lại nếu đúng )

Mã và tài liệu của anh ấy là tốt, theo ý kiến ​​của tôi. Lưu ý rằng mã tự ghi không có nghĩa là không nên có ý kiến, mà chỉ là không nên có ý kiến ​​không cần thiết. Tuy nhiên, điều này là bằng cách đọc mã (bao gồm cả nhận xét và nhận xét tài liệu) sẽ mang lại hiểu biết ngay lập tức về những gì mã làm và tại sao. Nếu mã "tự ghi lại" mất nhiều thời gian để hiểu hơn mã nhận xét, thì đó không thực sự là tài liệu tự ghi.

Chà, vì đây là về ý kiến ​​và mã, chúng ta hãy xem một số mã thực tế. So sánh mã điển hình này:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

Đối với mã tự viết tài liệu này, cho thấy những gì đang được thực hiện:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Và sau đó đến mã tài liệu này, giải thích rõ hơn tại sao nó được thực hiện:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Và phiên bản cuối cùng của mã làm tài liệu với số bình luận cần thiết:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Đây là một ví dụ về phong cách bình luận kém:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

Trong ví dụ cuối cùng, các bình luận được sử dụng khi các biến nên được đặt tên mô tả thay vào đó và kết quả của một hoạt động được tóm tắt khi chúng ta có thể thấy rõ hoạt động đó là gì. Tôi thích ví dụ thứ hai tự viết tài liệu này bất cứ ngày nào, và có lẽ đó là những gì bạn của bạn đang nói về khi anh ấy nói mã tự viết.

Tôi sẽ nói rằng nó phụ thuộc vào bối cảnh của những gì bạn đang làm. Đối với tôi, mã tự ghi có lẽ là đủ trong trường hợp này, nhưng một nhận xét mô tả chi tiết phương pháp đằng sau những gì được thực hiện (trong ví dụ này, phương trình) cũng hữu ích.

Bản thân mã luôn luôn là lời giải thích cập nhật nhất về những gì mã của bạn làm, nhưng theo tôi thì rất khó để giải thích ý định , đó là khía cạnh quan trọng nhất của các bình luận. Nếu nó được viết đúng cách, chúng ta đã biết những gì mã lệnh thực hiện, chúng ta chỉ cần biết lý do tại sao trên trái đất nó có phải nó!

Ai đó đã từng nói

1) Chỉ viết bình luận cho mã đó là khó hiểu.
2) Cố gắng không viết mã khó hiểu.

Ý tưởng đằng sau mã "tự viết tài liệu" là logic chương trình thực tế trong mã đủ rõ ràng để giải thích cho bất kỳ ai đọc mã không chỉ mã đang làm gì mà tại sao nó lại làm như vậy.

Theo tôi, ý tưởng về mã tự viết tài liệu thực sự là một huyền thoại. Mã có thể cho bạn biết logic đằng sau những gì đang xảy ra, nhưng nó không thể giải thích tại sao nó được thực hiện theo một cách nhất định, đặc biệt nếu có nhiều hơn một cách để giải quyết vấn đề. Vì lý do đó một mình nó không bao giờ có thể thay thế mã nhận xét tốt .

Tôi nghĩ nó có liên quan để đặt câu hỏi liệu một dòng mã cụ thể có tự viết tài liệu hay không, nhưng cuối cùng nếu bạn không hiểu cấu trúc và chức năng của một lát mã thì hầu hết các bình luận sẽ không có ích. Lấy ví dụ, đoạn mã "nhận xét chính xác" của amdfan:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

Mã này là tốt, nhưng sau đây là thông tin tương tự trong hầu hết các hệ thống phần mềm hiện đại và nhận ra một cách rõ ràng rằng sử dụng phép tính Newton là một lựa chọn có thể được thay đổi nếu một số mô hình vật lý khác phù hợp hơn:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

Theo kinh nghiệm cá nhân của riêng tôi, có rất ít tình huống mã hóa "bình thường" mà bạn thực sự cần bình luận. Làm thế nào thường xuyên bạn kết thúc việc lăn thuật toán của riêng bạn, ví dụ? Về cơ bản mọi thứ khác là vấn đề cấu trúc hệ thống của bạn để một lập trình viên có thể hiểu được các cấu trúc đang sử dụng và các lựa chọn thúc đẩy hệ thống sử dụng các cấu trúc cụ thể đó.

Tôi quên nơi tôi đã nhận được điều này, nhưng:

Mỗi bình luận trong một chương trình giống như một lời xin lỗi đến người đọc. "Tôi xin lỗi vì mã của tôi mờ đến mức bạn không thể hiểu nó bằng cách nhìn vào nó". Chúng ta chỉ cần chấp nhận rằng chúng ta không hoàn hảo nhưng cố gắng để trở nên hoàn hảo và tiếp tục xin lỗi khi chúng ta cần.

Trước hết, thật tốt khi biết rằng mã của đồng nghiệp của bạn trên thực tế rõ ràng hơn các mã khác mà bạn đã thấy. Điều đó có nghĩa là anh ta có thể không sử dụng "tài liệu tự" như một lý do cho việc quá lười biếng để nhận xét mã của mình.

Mã tự viết tài liệu là mã không yêu cầu bình luận văn bản miễn phí cho người đọc có hiểu biết để hiểu những gì nó đang làm. Ví dụ, đoạn mã này là tài liệu tự:

print "Hello, World!"

và đây là:

factorial n = product [1..n]

và đây là:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

Bây giờ, ý tưởng về một "người đọc thông tin" là rất chủ quan và tình huống. Nếu bạn hoặc bất kỳ ai khác gặp khó khăn khi tuân theo mã của đồng nghiệp, thì anh ta sẽ làm tốt việc đánh giá lại ý tưởng của mình về một độc giả có hiểu biết. Một số mức độ quen thuộc với ngôn ngữ và thư viện đang được sử dụng phải được giả sử để gọi mã tự ghi mã.

Lập luận tốt nhất mà tôi đã thấy khi viết "mã tự ghi" là nó tránh được vấn đề bình luận văn bản tự do không đồng ý với mã khi nó được viết. Sự chỉ trích tốt nhất là trong khi mã có thể mô tả chính nó và cách nó đang làm, nó không thể giải thích tại sao một cái gì đó được thực hiện theo một cách nhất định.

Mã tự viết tài liệu là một ví dụ hay về "DRY" (Đừng lặp lại chính mình). Không trùng lặp thông tin trong các bình luận, hoặc có thể, trong chính mã.

Thay vì giải thích những gì một biến được sử dụng cho, đổi tên biến.

Thay vì giải thích những đoạn mã ngắn làm gì, hãy trích xuất nó thành một phương thức và đặt cho nó một tên mô tả (có lẽ là một phiên bản rút gọn của văn bản nhận xét của bạn).

Thay vì giải thích những gì một bài kiểm tra phức tạp làm, hãy trích xuất nó thành một phương thức và đặt cho nó một cái tên hay.

Vân vân.

Sau này, bạn kết thúc với mã không yêu cầu giải thích nhiều, nó tự giải thích, vì vậy bạn nên xóa các bình luận chỉ lặp lại thông tin trong mã.

Điều này không có nghĩa là bạn không có ý kiến ​​gì cả, có một số thông tin bạn không thể đưa vào mã như thông tin về ý định ("tại sao"). Trong trường hợp lý tưởng, mã và các bình luận bổ sung cho nhau, mỗi lần thêm giá trị giải thích duy nhất mà không trùng lặp thông tin trong nhau.

mã tự viết tài liệu là một thực hành tốt và nếu được thực hiện đúng cách có thể dễ dàng truyền đạt ý nghĩa của mã mà không cần đọc quá nhiều bình luận. đặc biệt là trong các tình huống mà tên miền được mọi người trong nhóm hiểu rõ.

Phải nói rằng, các bình luận có thể rất hữu ích cho những người mới đến hoặc cho những người thử nghiệm hoặc để tạo các tài liệu / tệp trợ giúp.

mã tự viết tài liệu + nhận xét cần thiết sẽ đi một chặng đường dài hướng tới việc giúp đỡ mọi người trong các nhóm.

Theo thứ tự:

• Mã tự viết tài liệu là mã thể hiện rõ ràng ý định của nó với người đọc.
• Không hoàn toàn. Bình luận luôn hữu ích cho bình luận về lý do tại sao một chiến lược cụ thể được chọn. Tuy nhiên, ý kiến ​​giải thích những gì một phần của mã đang làm là biểu thị cho mã không đủ tài liệu và có thể sử dụng một số cấu trúc lại ..
• Bình luận nói dối và trở nên lỗi thời. Mã luôn luôn có khả năng nói sự thật.
• Tôi chưa từng thấy một trường hợp những gì mã có thể không được thực hiện đầy đủ rõ ràng mà không bình luận; tuy nhiên, như tôi đã nói trước đây, đôi khi cần thiết / hữu ích để bao gồm bình luận về lý do tại sao .

Tuy nhiên, điều quan trọng cần lưu ý là mã tự viết tài liệu thực sự cần rất nhiều kỷ luật tự giác và đội nhóm. Bạn phải học cách lập trình khai báo nhiều hơn, và bạn phải rất khiêm tốn và tránh mã "thông minh" có lợi cho mã rõ ràng đến mức dường như bất cứ ai cũng có thể viết nó.

Khi bạn đọc "mã tự ghi", bạn sẽ thấy nó đang làm gì, nhưng bạn không thể luôn đoán tại sao nó lại hoạt động theo cách cụ thể đó.

Có hàng tấn các ràng buộc không lập trình như logic kinh doanh, bảo mật, nhu cầu của người dùng, v.v.

Khi bạn bảo trì, những thông tin backgorund đó trở nên rất quan trọng.

Chỉ là nhúm muối của tôi ...

Đối với một, hãy xem xét đoạn trích sau:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Trong ví dụ này, bạn có 5 dòng bình luận trên 3 dòng mã. Thậm chí tệ hơn - các bình luận không thêm bất cứ điều gì bạn không thể nhìn thấy bằng cách đọc mã. Nếu bạn có 10 phương pháp như thế này, bạn có thể nhận được 'mù nhận xét' và không nhận thấy một phương thức đi lệch khỏi mẫu.

Nếu tất nhiên, một phiên bản tốt hơn sẽ là:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

Tuy nhiên, đối với mã tầm thường tôi không muốn có ý kiến. Ý định và tổ chức tổng thể được giải thích tốt hơn trong một tài liệu riêng bên ngoài mã.

Sự khác biệt là giữa "cái gì" và "làm thế nào".

• Bạn nên ghi lại "những gì" một thói quen làm.
• Bạn không nên ghi lại "cách thức" thực hiện, trừ khi các trường hợp đặc biệt (ví dụ: tham khảo một bài viết thuật toán cụ thể). Điều đó nên được tự ghi lại.

Một điều mà bạn có thể muốn chỉ ra cho đồng nghiệp của mình là dù tài liệu của anh ấy có tự ghi lại như thế nào đi chăng nữa, nếu các phương pháp thay thế khác được xem xét và loại bỏ thì thông tin sẽ bị mất trừ khi anh ấy nhận xét mã với thông tin đó. Đôi khi, điều quan trọng là phải biết rằng một giải pháp thay thế đã được xem xét và lý do tại sao nó được quyết định chống lại và các bình luận mã có khả năng tồn tại theo thời gian.

Trong một công ty nơi tôi làm việc, một trong những lập trình viên bị mắc kẹt sau màn hình của cô ấy.

"Tài liệu mã của bạn giống như người duy trì nó là một kẻ điên cuồng sát nhân, người biết bạn sống ở đâu."

mã tự viết tài liệu thường sử dụng các tên biến khớp chính xác với những gì mã đang làm để dễ hiểu những gì đang diễn ra

Tuy nhiên, "mã tự ghi" như vậy sẽ không bao giờ thay thế các bình luận. Đôi khi mã chỉ quá phức tạp và mã tự ghi lại là không đủ, đặc biệt là trong cách duy trì.

Tôi đã từng có một giáo sư là một người tin tưởng vững chắc vào lý thuyết này Trong thực tế, điều tốt nhất tôi từng nhớ ông nói là "Nhận xét là cho những kẻ yếu đuối"
Lúc đầu, tất cả chúng tôi đều ngạc nhiên nhưng nó có ý nghĩa.
Tuy nhiên, tình huống là mặc dù bạn có thể hiểu những gì đang diễn ra trong mã nhưng một người ít kinh nghiệm hơn bạn có thể đến sau bạn và không hiểu chuyện gì đang xảy ra. Đây là khi ý kiến ​​trở nên quan trọng. Tôi biết nhiều lần chúng tôi không tin rằng chúng quan trọng nhưng có rất ít trường hợp bình luận là không cần thiết.

Tôi ngạc nhiên khi không có ai mang đến " Lập trình biết chữ ", một kỹ thuật được phát triển vào năm 1981 bởi Donald E. Knuth của TeX và "Nghệ thuật lập trình máy tính" nổi tiếng.

Tiền đề rất đơn giản: vì mã phải được hiểu bởi con người và các bình luận chỉ đơn giản là bị trình biên dịch vứt đi, tại sao không cung cấp cho mọi người thứ họ cần - một mô tả văn bản đầy đủ về ý định của mã, không bị thay đổi bởi các yêu cầu ngôn ngữ lập trình , cho người đọc và mã thuần cho trình biên dịch.

Các công cụ lập trình biết chữ làm điều này bằng cách cung cấp cho bạn đánh dấu đặc biệt cho một tài liệu cho các công cụ biết phần nào nên là nguồn và văn bản là gì. Chương trình sau đó trích xuất các phần mã nguồn ra khỏi tài liệu và tập hợp một tệp mã.

Tôi đã tìm thấy một ví dụ trên web của nó: http://moonflare.com/code/select/select.nw hoặc phiên bản HTML http://moonflare.com/code/select/select.html

Nếu bạn có thể tìm thấy cuốn sách của Knuth trên thư viện (Donald E. Knuth, Lập trình văn học, Stanford, California: Trung tâm nghiên cứu ngôn ngữ và thông tin, 1992, Ghi chú bài giảng CSLI, số 27.) bạn nên đọc nó.

Đó là mã tự viết tài liệu, hoàn chỉnh với lý luận và tất cả. Thậm chí làm cho một tài liệu tốt đẹp, mọi thứ khác chỉ là những bình luận được viết tốt :-)

Tôi muốn cung cấp thêm một quan điểm cho nhiều câu trả lời hợp lệ:

Mã nguồn là gì? Ngôn ngữ lập trình là gì?

Các máy không cần mã nguồn. Họ đang vui vẻ chạy lắp ráp. Ngôn ngữ lập trình là vì lợi ích của chúng tôi. Chúng tôi không muốn viết lắp ráp. Chúng ta cần hiểu những gì chúng ta đang viết. Lập trình là về viết mã.

Bạn có thể đọc những gì bạn viết không?

Mã nguồn không được viết bằng ngôn ngữ của con người. Nó đã được thử (ví dụ FORTRAN) nhưng không hoàn toàn thành công.

Mã nguồn không thể có sự mơ hồ. Đó là lý do tại sao chúng ta phải đặt nhiều cấu trúc trong đó hơn là làm với văn bản. Văn bản chỉ hoạt động với ngữ cảnh, mà chúng ta coi là đương nhiên khi chúng ta sử dụng văn bản. Bối cảnh trong mã nguồn luôn luôn là khám phá. Hãy suy nghĩ "sử dụng" trong C #.

Hầu hết các ngôn ngữ lập trình đều có dự phòng để trình biên dịch có thể bắt chúng ta khi chúng ta không kết hợp. Các ngôn ngữ khác sử dụng nhiều suy luận và cố gắng loại bỏ sự dư thừa đó.

Tên máy tính, tên phương thức và tên biến không cần thiết cho máy tính. Chúng được sử dụng bởi chúng tôi để tham khảo. Trình biên dịch không hiểu ngữ nghĩa, đó là cho chúng tôi sử dụng.

Ngôn ngữ lập trình là cầu nối ngôn ngữ giữa con người và máy móc. Nó phải được ghi cho chúng tôi và có thể đọc được cho họ. Nhu cầu thứ cấp là nó nên được đọc cho chúng tôi. Nếu chúng ta giỏi về ngữ nghĩa khi được phép và giỏi cấu trúc mã, mã nguồn sẽ dễ đọc ngay cả đối với chúng ta. Mã tốt nhất không cần bình luận.

Nhưng sự phức tạp ẩn giấu trong mỗi dự án, bạn luôn phải quyết định nơi đặt sự phức tạp và những con lạc đà nào để nuốt. Đó là những nơi để sử dụng ý kiến.

Mã tài liệu tự là một lựa chọn dễ dàng từ chối vấn đề, theo mã thời gian, nhận xét và phân kỳ tài liệu. Và nó là một yếu tố kỷ luật để viết mã rõ ràng (nếu bạn nghiêm khắc với chính mình).

Đối với tôi, đây là những quy tắc tôi cố gắng tuân theo:

• Mã phải dễ dàng và rõ ràng để đọc càng tốt.
• Nhận xét sẽ đưa ra lý do cho các quyết định thiết kế mà tôi đã đưa ra, như: tại sao tôi sử dụng thuật toán này hoặc các giới hạn mà mã có, như: không hoạt động khi ... (điều này nên được xử lý trong hợp đồng / xác nhận trong mã) (thường trong chức năng / thủ tục).
• Tài liệu nên liệt kê việc sử dụng (hội tụ cuộc gọi), tác dụng phụ, giá trị trả về có thể. Nó có thể được trích xuất từ ​​mã bằng các công cụ như jDoc hoặc xmlDoc. Do đó, nó thường nằm ngoài hàm / thủ tục, nhưng gần với mã mà nó mô tả.

Điều này có nghĩa là cả ba phương tiện mã tài liệu sống gần nhau và do đó có nhiều khả năng bị thay đổi khi mã thay đổi, nhưng không trùng lặp với những gì chúng thể hiện.

Vấn đề thực sự với cái gọi là mã tự viết tài liệu là nó truyền tải những gì nó thực sự làm. Mặc dù một số ý kiến ​​có thể giúp ai đó hiểu mã tốt hơn (ví dụ: các bước thuật toán, v.v.), nó ở mức độ dư thừa và tôi nghi ngờ bạn sẽ thuyết phục được đồng nghiệp của mình.

Tuy nhiên, điều thực sự quan trọng trong tài liệu là những thứ không rõ ràng trực tiếp từ mã: mục đích cơ bản, giả định, tác động, hạn chế, v.v.

Có thể xác định rằng một mã làm X từ một cái nhìn nhanh chóng dễ dàng hơn nhiều so với việc xác định rằng một mã không làm Y. Anh ta phải ghi lại Y ...

Bạn có thể chỉ cho anh ta một ví dụ về một mã có vẻ tốt, rõ ràng, nhưng thực tế không bao gồm tất cả các cơ sở của đầu vào, và xem liệu anh ta có tìm thấy nó không.

Tôi nghĩ rằng mã tự viết tài liệu là một thay thế tốt để bình luận. Nếu bạn yêu cầu các bình luận để giải thích cách thức hoặc lý do mã là như vậy, thì bạn có một hàm hoặc tên biến cần được sửa đổi để được giải thích nhiều hơn. Nó có thể tùy thuộc vào người viết mã về việc liệu anh ta sẽ bù đắp sự thiếu hụt bằng một nhận xét hoặc đổi tên một số biến và chức năng và tái cấu trúc mã mặc dù.

Nó thực sự không thể thay thế tài liệu của bạn, bởi vì tài liệu là những gì bạn cung cấp cho người khác để giải thích cách sử dụng hệ thống của bạn, thay vì cách thức thực hiện.

Chỉnh sửa: Tôi (và có lẽ mọi người khác) có lẽ nên có quy định rằng ứng dụng Xử lý tín hiệu số (DSP) phải được nhận xét rất tốt. Điều đó chủ yếu là vì các ứng dụng DSP về cơ bản là 2 vòng lặp được cung cấp với các mảng giá trị và cộng / nhân / giá trị đã nói ... để thay đổi chương trình bạn thay đổi giá trị trong một trong các mảng ... cần một vài nhận xét để nói gì bạn đang làm trong trường hợp đó;)

Khi viết mã toán học, đôi khi tôi thấy hữu ích khi viết các bình luận dài, giống như bài luận, giải thích toán học, các quy ước công chứng mà mã sử dụng và cách tất cả khớp với nhau. Chúng ta đang nói hàng trăm dòng tài liệu ở đây.

Tôi cố gắng làm cho mã của mình tự viết tài liệu càng tốt, nhưng khi tôi quay lại làm việc với nó sau một vài tháng, tôi thực sự cần phải đọc lời giải thích để tránh bị băm khỏi nó.

Bây giờ, tất nhiên loại biện pháp cực đoan này không cần thiết cho hầu hết các trường hợp. Tôi nghĩ rằng đạo đức của câu chuyện là: mã khác nhau đòi hỏi số lượng tài liệu khác nhau. Một số mã có thể được viết rõ ràng đến mức nó không cần bình luận - vì vậy hãy viết nó rõ ràng và không sử dụng bình luận ở đó!

Nhưng rất nhiều mã cần có ý kiến ​​để có ý nghĩa, vì vậy hãy viết nó càng rõ ràng càng tốt và sau đó sử dụng càng nhiều bình luận càng cần ...

Tôi sẽ tranh luận - như nhiều bạn làm - rằng để thực sự tự ghi lại, mã cần thể hiện một số hình thức của ý định. Nhưng tôi ngạc nhiên không ai đề cập đến BDD - Phát triển hướng hành vi . Một phần của ý tưởng là bạn có các bài kiểm tra tự động (mã) giải thích mục đích của mã của bạn, điều này rất khó để làm rõ ràng bằng cách khác.

Mô hình miền tốt 
+ tên tốt (variabes, phương thức, lớp) 
+ ví dụ mã (kiểm tra đơn vị từ các trường hợp sử dụng) 
= phần mềm tự viết tài liệu 

Một vài lý do tại sao các bình luận thêm ngoài mã có thể rõ ràng hơn:

• Mã bạn đang xem được tạo tự động và do đó mọi chỉnh sửa đối với mã có thể bị ghi đè vào lần tiếp theo khi dự án được biên dịch
• Việc triển khai ít hơn đơn giản đã được đánh đổi để đạt được hiệu suất (bỏ kiểm soát một vòng lặp, tạo bảng tra cứu cho một phép tính đắt tiền, v.v.)

Nó sẽ là tất cả trong những gì nhóm đánh giá cao trong tài liệu của mình. Tôi sẽ đề nghị rằng ghi lại lý do tại sao / ý định thay vì quan trọng như thế nào và điều này không phải lúc nào cũng được ghi lại trong mã tài liệu. get / set không có những điều này là hiển nhiên - nhưng tính toán, truy xuất, v.v ... một số lý do tại sao nên được thể hiện.

Ngoài ra, hãy chú ý đến sự khác biệt trong nhóm của bạn nếu bạn đến từ các quốc tịch khác nhau. Sự khác biệt trong từ điển có thể dẫn đến việc đặt tên cho các phương thức:

Tìm kiếm băm

Tìm kiếm nhị phân

Nhị phân

Ba phương pháp này được đóng góp từ các nhà phát triển được đào tạo ở 3 châu lục khác nhau làm điều tương tự. Chỉ bằng cách đọc các bình luận mô tả thuật toán, chúng tôi mới có thể xác định được sự trùng lặp trong thư viện của chúng tôi.

Đối với tôi đọc mã cần bình luận cũng giống như đọc văn bản bằng ngôn ngữ mà tôi không biết. Tôi thấy tuyên bố và tôi không hiểu nó làm gì hoặc tại sao - và tôi phải xem các bình luận. Tôi đọc một cụm từ và tôi cần tìm trong từ điển để hiểu ý nghĩa của nó.

Nó thường dễ dàng để viết mã mà tự ghi lại những gì nó làm. Để cho bạn biết lý do tại sao nó làm như vậy bình luận là phù hợp hơn, nhưng ngay cả ở đây mã có thể tốt hơn. Nếu bạn hiểu hệ thống của mình ở mọi cấp độ trừu tượng, bạn nên thử tổ chức mã cho mình như

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

Tên phương thức phản ánh ý định của bạn và cơ thể phương thức giải thích cách bạn đạt được mục tiêu của mình. Dù sao, bạn không thể nói toàn bộ cuốn sách trong tiêu đề của nó, vì vậy những tóm tắt chính của hệ thống của bạn vẫn phải được ghi lại, cũng như các thuật toán phức tạp, các hợp đồng và các tạo tác phương pháp không tầm thường.

Nếu mã mà đồng nghiệp của bạn sản xuất thực sự là tài liệu tự - bạn may mắn và bạn. Nếu bạn nghĩ rằng mã đồng nghiệp của bạn cần bình luận - nó cần. Chỉ cần mở vị trí không tầm thường nhất trong đó, đọc nó một lần và xem bạn có hiểu mọi thứ hay không. Nếu mã là tài liệu tự - thì bạn nên. Nếu không - hãy hỏi đồng nghiệp của bạn một câu hỏi về nó, sau khi anh ta đưa ra câu trả lời, hãy hỏi tại sao câu trả lời đó không được ghi lại trong các bình luận hoặc mã trước đó. Anh ta có thể tuyên bố rằng mã là tài liệu tự cho người thông minh như anh ta, nhưng dù sao anh ta cũng phải tôn trọng các thành viên khác trong nhóm - nếu nhiệm vụ của bạn yêu cầu hiểu mã của anh ta và mã của anh ta không giải thích cho bạn mọi thứ bạn cần hiểu - nó cần bình luận.

Hầu hết các tài liệu / nhận xét phục vụ cho việc hỗ trợ các nhà cải tiến / phát triển mã trong tương lai do đó làm cho mã có thể được duy trì. Thường xuyên hơn không, chúng tôi sẽ quay trở lại mô-đun của mình sau đó để thêm các tính năng mới hoặc tối ưu hóa. Vào thời điểm đó, sẽ dễ hiểu mã hơn bằng cách đọc các bình luận hơn là bước qua nhiều điểm dừng. Bên cạnh đó tôi thà dành thời gian suy nghĩ cho logic mới hơn là giải mã cái hiện có.

Tôi nghĩ những gì anh ta có thể nhận được là nếu các bình luận giải thích những gì mã đang làm thì nên viết lại để rõ ràng ý định của nó là gì. Đó là những gì anh ấy có nghĩa là bằng cách tự viết mã. Thông thường, điều này có thể chỉ đơn giản là chia nhỏ hàm dài thành các phần logic nhỏ hơn với tên hàm mô tả.

Điều đó không có nghĩa là mã không nên được bình luận. Nó có nghĩa là các bình luận nên cung cấp một lý do tại sao mã được viết theo cách của nó.

Tôi tin rằng bạn nên luôn cố gắng để đạt được mã tự viết tài liệu bởi vì nó giúp đọc mã dễ dàng hơn. Tuy nhiên, bạn cũng phải thực dụng về mọi thứ.

Ví dụ, tôi thường thêm một nhận xét cho mọi thành viên trong lớp (tôi sử dụng các nhận xét tài liệu cho việc này). Điều này mô tả những gì thành viên phải làm nhưng không phải làm thế nào. Tôi thấy rằng khi tôi đang đọc qua mã, đặc biệt là mã cũ, điều này giúp tôi nhớ nhanh thành viên đó để làm gì và tôi cũng thấy nó dễ hơn đọc mã và xử lý nó, đặc biệt nếu dòng mã nhảy xung quanh khá nhiều .

Đây chỉ là ý kiến ​​của tôi. Tôi biết rất nhiều người làm việc mà không có ý kiến ​​gì cả và nói rằng họ thấy điều này không có vấn đề gì. Tuy nhiên, tôi đã hỏi ai đó về một phương pháp họ đã viết sáu tháng trước và họ đã phải suy nghĩ trong vài phút để cho tôi biết chính xác những gì nó đã làm. Đây không phải là một vấn đề nếu phương pháp được bình luận.

Cuối cùng, bạn phải nhớ rằng các bình luận là một phần không kém của hệ thống dưới dạng mã. Khi bạn tái cấu trúc và thay đổi chức năng, bạn cũng phải cập nhật ý kiến ​​của mình. Đây là một lập luận chống lại việc sử dụng các bình luận vì chúng tồi tệ hơn vô dụng nếu chúng không chính xác.