Làm thế nào để đối phó với tautology trong ý kiến? [đóng cửa]

Đôi khi tôi thấy mình trong tình huống khi một phần của mã mà tôi đang viết là (hoặc dường như ) rất rõ ràng rằng tên của nó về cơ bản sẽ được lặp lại như một nhận xét:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(Ví dụ về C #, nhưng vui lòng xem câu hỏi là bất khả tri về ngôn ngữ).

Một nhận xét như thế là vô ích; tôi đang làm gì sai Có phải sự lựa chọn của tên là sai? Làm thế nào tôi có thể nhận xét những phần như thế này tốt hơn? Tôi có nên bỏ qua bình luận cho những thứ như thế này?

Trong hầu hết các dự án tôi làm, không có nhiều thời gian để viết bình luận chi tiết cho từng thành viên trong lớp.

Điều đó không có nghĩa là không có thời gian cho ý kiến; ngược lại, có rất nhiều thời gian cho các bình luận tautological cho rằng một phiên bản bị chê lại của bất cứ điều gì đang được bình luận. Họ làm việc tuyệt vời như một điểm khởi đầu .

Đặc biệt với việc sử dụng các bình luận của Visual Studio đi kèm với IntelliSense , nên bắt đầu với một chút thông tin về lĩnh vực này:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Và sau đó khi bạn tiếp tục viết mã, khi bạn không thể nhớ UpdateLocationđược đó là vị trí mà bản cập nhật đã diễn ra hay vị trí mà bản cập nhật được gửi đến, bạn sẽ phải xem lại mã. Tại thời điểm này, bạn nên thêm thông tin bổ sung đó:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Nếu có một lập trình viên khác hỏi bạn về chi tiết trên một lĩnh vực, hãy cập nhật các nhận xét với thông tin đó:

Những loại cập nhật nên Example.UpdateLocationđược sử dụng để lưu trữ?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Giống như một chương trình có lỗi, bình luận tốt có lỗi cần được lặp đi lặp lại. Mục đích của các bình luận là để giúp hiểu mã khi bạn truy cập lại sáu tháng sau đó và không thể nhớ bất cứ điều gì về cách chương trình hoạt động.

Và cũng giống như lập trình, ý kiến ​​của bạn phải bắt đầu từ đâu đó. Nhận xét Tautological là các Hello World!ý kiến, khi bạn thực hành viết và cập nhật tài liệu, tài liệu bắt đầu của bạn sẽ ngày càng trở nên kiên cường hơn.

Bình luận không bao giờ nên sao chép mã của bạn. Nhận xét không nên trả lời câu hỏi " làm thế nào? ", Mà chỉ " tại sao? " Và " cái gì? ". Tại sao một thuật toán như vậy được chọn, các giả định ngầm định ở đây là gì (trừ khi ngôn ngữ của bạn đủ mạnh để diễn đạt nó với hệ thống loại, hợp đồng và tương tự), lý do để làm điều này là gì, v.v.

Tôi khuyên bạn nên xem thực hành Lập trình Văn học để tìm cảm hứng.

Nhận xét nên mô tả mã, không trùng lặp nó. Nhận xét tiêu đề này chỉ trùng lặp. Để nó ra.

Để chúng ra ngoài!

Thông thường, đó là một thực hành tốt để loại bỏ các bình luận trong đó thông tin thể hiện trong đó đã có mặt ở nơi khác. Nếu bạn có thể thể hiện mục đích của một phương pháp rõ ràng và rõ ràng bằng cách đặt cho nó một cái tên hay thì không cần phải bình luận .

Đặt chúng vào!

Ví dụ của bạn minh họa hai trường hợp ngoại lệ cho quy tắc này:

Đầu tiên, "Cập nhật vị trí" có thể (tùy thuộc vào ngữ cảnh) không rõ ràng. Trong trường hợp đó, bạn cần phải đặt tên tốt hơn hoặc đưa ra nhận xét để xóa bỏ sự mơ hồ. Cải thiện tên nói chung là tùy chọn tốt hơn, nhưng điều này không phải lúc nào cũng có thể (ví dụ khi bạn đang triển khai API được xuất bản).

Thứ hai, "///" trong C # cho biết một nhận xét được dự định sẽ được sử dụng để tự động tạo tài liệu. IDE sử dụng các nhận xét này cho các mẹo về công cụ và có các công cụ (Sandcastle) có thể tạo các tệp trợ giúp và vv từ các nhận xét này. Như vậy, có các đối số để chèn các nhận xét này ngay cả khi các phương thức mà chúng ghi lại đã có tên mô tả. Tuy nhiên, ngay cả sau đó, nhiều nhà phát triển có kinh nghiệm sẽ nhăn mặt về sự trùng lặp thông tin. Yếu tố quyết định nên là nhu cầu của những người mà tài liệu dự định.

Tôi hoàn toàn không đồng ý với câu trả lời "không viết bình luận". Tại sao? Hãy để tôi chỉ ra bằng cách thay đổi ví dụ của bạn một chút.

public Uri UpdateLocation ();

Vậy chức năng này làm gì:

• Nó có trả về "vị trí cập nhật" không? hoặc là
• Nó có "cập nhật" vị trí và trả lại vị trí mới không?

Bạn có thể thấy rằng không có bình luận thì có sự mơ hồ. Một người mới có thể dễ dàng phạm sai lầm.

Trong ví dụ của bạn, nó là một thuộc tính nên các phương thức "get / set" tiết lộ rằng tùy chọn thứ hai không chính xác và nó thực sự có nghĩa là "cập nhật vị trí" chứ không phải "cập nhật vị trí". Nhưng nó quá dễ để phạm sai lầm này, đặc biệt là trong trường hợp những từ mơ hồ như "cập nhật". Chơi an toàn. Đừng nhầm lẫn ai đó mới chỉ để tiết kiệm một vài giây thời gian của bạn.

/// <summary>các khối được sử dụng để tạo tài liệu cho tài liệu IntelliSense và API .

Do đó, nếu đây là API hướng tới công chúng, bạn phải luôn bao gồm ít nhất một <summary>nhận xét, ngay cả khi mục đích của chức năng phải hiển nhiên đối với người đọc.

Tuy nhiên, đây là ngoại lệ của quy tắc; nói chung, chỉ cần nhớ DRY (Đừng lặp lại chính mình) .

Chỉ điền vào những bình luận như thế nếu bạn biết bạn sẽ được lợi như thế nào từ những thứ như thế; Nếu không thì chỉ cần lau chúng.

_{Đối với tôi, trường hợp lợi ích rõ ràng là khi có một kiểm tra tự động cho các bình luận bị thiếu và tôi đang sử dụng kiểm tra đó để phát hiện mã nơi cần điền thông tin quan trọng; vì điều này tôi thực sự đã lấp đầy một số chỗ dành sẵn - chỉ để đảm bảo rằng báo cáo công cụ không chứa "báo động sai".}

Tôi nghĩ luôn có cách để tránh sự trùng lặp trắng trợn . Trong nhiều năm qua, tôi đã sử dụng vài "bộ đệm mẫu" cho các trường hợp như của bạn - chủ yếu là tên tự mô tả và xem ở trên .

Trong ví dụ cụ thể này, tôi sẽ sử dụng một cái gì đó thuộc loại "tự mô tả" (giả sử đó không phải là trường hợp xóa sổ sẽ thực hiện công việc), như thế:

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{Ví dụ khi tôi có thể sử dụng xem các loại chất độn ở trên sẽ là các bình luận Javadoc yêu cầu các trường chuyên dụng cho giá trị trả về, tham số và ngoại lệ. Rất thường xuyên, tôi thấy rằng sẽ tốt hơn khi mô tả hầu hết hoặc thậm chí tất cả những điều này trong câu tóm tắt duy nhất, phương thức trả về <mô tả những gì được trả về> cho các tham số được cung cấp <mô tả tham số> . Trong trường hợp như vậy, tôi điền vào các trường bắt buộc chính thức với xem đơn giản ở trên , trỏ người đọc đến mô tả tóm tắt.}

Đây là một câu hỏi tôi muốn tự hỏi mình khi suy nghĩ về việc có nên thêm nhận xét vào một phần của mã không: Tôi có thể truyền đạt điều gì để giúp người tiếp theo hiểu rõ hơn về mục đích chung của mã, để họ có thể cập nhật, sửa chữa hoặc mở rộng nó nhanh hơn và đáng tin cậy hơn?

Đôi khi, câu trả lời chính xác cho câu hỏi này là không có gì nhiều bạn có thể thêm vào thời điểm đó trong mã, bởi vì bạn đã chọn tên và quy ước làm cho ý định trở nên rõ ràng nhất có thể. Điều đó có nghĩa là bạn đã viết mã tự viết tài liệu vững chắc và việc chèn một nhận xét ở đó có thể sẽ làm mất giá trị nhiều hơn nó sẽ giúp ích. (Lưu ý rằng các nhận xét dư thừa thực sự có thể làm hỏng độ tin cậy của mã theo thời gian bằng cách làm chậm sự không đồng bộ với mã thực theo thời gian và do đó làm cho việc giải mã ý định thực sự khó khăn hơn.

Tuy nhiên, trong hầu hết mọi chương trình và trong bất kỳ ngôn ngữ lập trình nào, bạn sẽ gặp phải những điểm mà các khái niệm và quyết định quan trọng nhất định được lập trình viên ban đầu - bởi bạn - sẽ không còn rõ ràng trong mã. Điều này là không thể tránh khỏi bởi vì một lập trình viên giỏi luôn lập trình cho tương lai - nghĩa là, không chỉ để chương trình hoạt động một lần, mà còn tạo ra tất cả nhiều bản sửa lỗi và phiên bản và mở rộng và sửa đổi trong tương lai và ai biết phải làm gì cũng hoạt động chính xác. Rằng mục tiêu sau đó khó hơn rất nhiều, và đòi hỏi nhiều suy nghĩ hơn để làm tốt. Nó cũng rất khó để thể hiện tốt trong hầu hết ngôn ngữ máy tính, đó là tập trung hơn vào chức năng - có nghĩa là, trên nói những gì hiện này phiên bản của chương trình cần phải làm, ngay bây giờ, để làm cho nó thỏa đáng.

Đây là một ví dụ đơn giản về những gì tôi muốn nói. Trong hầu hết các ngôn ngữ, một tìm kiếm nội tuyến nhanh chóng về cấu trúc dữ liệu nhỏ sẽ có đủ độ phức tạp để ai đó lần đầu tiên nhìn vào nó có thể sẽ không nhận ra ngay đó là gì. Đó là cơ hội cho một nhận xét tốt, bởi vì bạn có thể thêm một cái gì đó về ý định mã của bạn mà người đọc sau này có thể sẽ đánh giá cao ngay lập tức vì hữu ích cho việc giải mã các chi tiết.

Ngược lại, trong các ngôn ngữ như ngôn ngữ dựa trên logic Prolog, việc thể hiện tìm kiếm một danh sách nhỏ có thể rất tầm thường và cô đọng đến nỗi mọi bình luận bạn có thể thêm sẽ chỉ là tiếng ồn. Vì vậy, bình luận tốt nhất thiết phải phụ thuộc vào bối cảnh. Điều đó bao gồm các yếu tố như thế mạnh của ngôn ngữ bạn đang sử dụng và bối cảnh chương trình tổng thể.

Điểm mấu chốt là đây: Nghĩ đến tương lai. Tự hỏi bản thân điều gì là quan trọng và rõ ràng đối với bạn về cách chương trình nên được hiểu và sửa đổi trong tương lai. [1]

Đối với những phần trong mã của bạn thực sự là tài liệu tự động, các bình luận chỉ cần thêm nhiễu và tăng vấn đề kết hợp cho các phiên bản trong tương lai. Vì vậy, đừng thêm chúng ở đó.

Nhưng đối với những phần trong mã của bạn, nơi bạn đã đưa ra quyết định quan trọng từ một số tùy chọn hoặc khi bản thân mã đủ phức tạp, mục đích của nó không rõ ràng, xin vui lòng, hãy thêm kiến ​​thức đặc biệt của bạn dưới dạng nhận xét. Một nhận xét tốt trong trường hợp như vậy là một nhận xét cho phép một số lập trình viên tương lai biết điều gì phải được giữ nguyên - đó là khái niệm về một khẳng định bất biến, tình cờ - và điều gì là ổn để thay đổi.

[1] Điều này vượt xa vấn đề bình luận, nhưng đáng để đưa ra: Nếu bạn thấy rằng bạn có một ý tưởng rất rõ ràng về cách mã của bạn có thể thay đổi trong tương lai, bạn có thể nên nghĩ xa hơn là chỉ nhận xét và nhúng các tham số đó trong chính mã, vì điều đó hầu như sẽ luôn là một cách đáng tin cậy hơn để đảm bảo độ tin cậy của các phiên bản mã trong tương lai của bạn hơn là cố gắng sử dụng các nhận xét để điều khiển một người không biết tương lai đi đúng hướng. Đồng thời bạn cũng muốn tránh tăng trưởng quá mức, vì con người nổi tiếng là không tốt trong việc dự đoán tương lai, và điều đó bao gồm cả tương lai của những thay đổi chương trình. Vì vậy, hãy cố gắng xác định và nắm bắt các khía cạnh hợp lý và đã được chứng minh của tương lai ở tất cả các cấp thiết kế chương trình, nhưng đừng

Trong mã riêng của mình, tôi sẽ thường xuyên để lại các tautology bình luận, bao gồm cả những thứ đặc biệt nghiêm trọng như:

<?php
// return the result
return $result;
?>

... Điều này rõ ràng đóng góp rất ít về mặt làm cho mã dễ hiểu hơn từ góc độ giải thích.

Tuy nhiên, trong suy nghĩ của tôi, những nhận xét này vẫn có giá trị, nếu chúng giúp duy trì tính nhất quán trực quan của các mẫu màu trong cú pháp tô sáng của bạn .

Tôi nghĩ rằng mã có cấu trúc rất giống với ngôn ngữ tiếng Anh, trong đó có "câu" và "đoạn văn" (mặc dù một "đoạn" có thể bao gồm hoàn toàn một "câu"). Tôi thường bao gồm một ngắt dòng và tóm tắt một dòng trên mỗi "đoạn". Ví dụ:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(Bỏ qua mã không đầy đủ, SQL tiêm, v.v. Bạn có ý tưởng.)

Đối với tôi, bình luận cuối cùng thực sự bổ sung giá trị cho mã, đơn giản vì nó giúp phân định trực quan một "đoạn" từ một đoạn khác bằng cách duy trì một sơ đồ tô màu nhất quán.

Bình luận nên được sử dụng để làm một trong những điều sau đây.

1. Thông tin cho các trình tạo tài liệu để lấy. Điều này không thể được đánh giá thấp, điều này là vô cùng quan trọng.
2. Cảnh báo về lý do tại sao một đoạn mã là như vậy, và những điều cần cân nhắc khác. Tôi đã xử lý mã được viết bằng 2 ngôn ngữ lập trình. Một phần quan trọng của điều này là có một cấu trúc chung giữa hai ngôn ngữ. Một nhận xét ở cả hai địa điểm thông báo cho người dùng rằng nếu họ thay đổi số này, họ cũng cần thay đổi một số khác là vô cùng hữu ích.
3. Viết ghi chú để giải thích tại sao một đoạn mã trông đặc biệt kỳ lạ lại như vậy. Nếu bạn phải suy nghĩ về cách làm cho một đoạn mã hoạt động theo một cách cụ thể và giải pháp không rõ ràng ngay từ đầu, có lẽ bạn nên giải thích về những gì bạn đang cố gắng làm.
4. Dán nhãn đầu vào / đầu ra, nếu chúng không rõ ràng. Thật tốt khi biết đầu vào của bạn dự kiến ​​là gì và chúng ở định dạng nào.

Bình luận không nên được sử dụng để làm như sau:

1. Giải thích những điều cực kỳ rõ ràng. Tôi đã từng thấy mã di sản như thế này : page=0; // Sets the page to 0. Tôi nghĩ rằng bất kỳ cá nhân có thẩm quyền có thể tìm ra điều đó.

Tôi sẽ loại bỏ tautology nhưng giữ bình luận, tôi sẽ bình luận các thuộc tính và tên biến bằng cách đưa ra một giá trị mẫu, để việc sử dụng được hiểu rõ ràng:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Bây giờ tôi biết chính xác những gì đi vào đó, và từ nhận xét, tôi có một ý tưởng rõ ràng về cách sử dụng nó.

Tôi muốn nói rằng nó phụ thuộc vào mục đích của các bình luận.

Nếu chúng được sử dụng để tạo tài liệu để nhóm xây dựng sử dụng (hoặc nếu chúng chỉ là những bình luận nội tuyến để giải thích mọi thứ), thì tôi nghĩ có thể chấp nhận bỏ qua điều đó. Có thể giả định một cách an toàn rằng nó tự giải thích; và khi không, có những thành viên khác trong nhóm có thể giải thích điều đó. Tất nhiên, nếu nó không hiển nhiên đối với nhiều người, bạn nên thêm nó vào.

Nếu các ý kiến ​​sẽ tạo tài liệu cho một số nhóm ở xa về mặt địa lý, thì tôi sẽ đặt mọi tài liệu vào đó.

Tôi nghĩ chủ đề này đã được thảo luận khá rộng rãi dưới những cái tên như "bình luận: chống mẫu" hoặc "bình luận có phải là mùi mã không?" ( một ví dụ ).

Tôi có xu hướng đồng ý với ý kiến ​​chung rằng các bình luận nên thêm thông tin mới, không trùng lặp. Bằng cách thêm các nhận xét tầm thường như thế, bạn đang vi phạm DRY và giảm tỷ lệ tín hiệu thành nhiễu của mã. Tôi có xu hướng tìm các bình luận cấp cao giải thích các trách nhiệm, lý do đằng sau và việc sử dụng ví dụ của lớp hữu ích hơn nhiều so với các bình luận trên mỗi tài sản (đặc biệt là các bình luận thừa).

Cá nhân, trong ví dụ của bạn, tôi sẽ để lại nhận xét (nếu thực sự không có gì hữu ích để thêm về tài sản).

Nếu bạn có thể viết mã không yêu cầu bình luận thì bạn đã đạt được niết bàn lập trình!.

Càng ít bình luận mã của bạn yêu cầu mã càng tốt!

Một nhận xét như thế là vô ích; tôi đang làm gì sai

Nó chỉ có vẻ vô dụng nếu bạn đã biết những gì UpdateLocationlàm. Là "cập nhật" ở đây một động từ hoặc một danh từ bổ trợ? Đó là, đây là cái gì đó cập nhật vị trí, hay nó là vị trí của bản cập nhật? Người ta có thể suy ra cái sau từ thực tế UpdateLocationrõ ràng là một tài sản, nhưng điểm lớn hơn là đôi khi nó không gây hại gì khi nói rõ ràng một cái gì đó có vẻ rõ ràng.

Tự động biên dịch tài liệu sang một bên, mã nên tự tạo tài liệu, để các bình luận chỉ nên ghi lại tài liệu khi mã không đủ để tự tạo tài liệu.

"Vị trí" là một điều hiển nhiên, nhưng "Cập nhật" có thể hơi mơ hồ. Nếu bạn không thể viết một cái tên tốt hơn, thì bạn có thể cung cấp chi tiết hơn trong bình luận không? Cập nhật những gì? Tại sao chúng ta cần điều này? Một số giả định (là null cho phép) là gì?