Bình luận / Kiểu tài liệu trong mã

Đây có thể là một câu hỏi ngu ngốc, nhưng nó đã ở sau đầu tôi một lúc và tôi không thể tìm thấy một câu trả lời đàng hoàng ở bất cứ nơi nào khác.

Tôi có một giáo viên nói rằng chúng ta nên liệt kê rõ ràng từng tham số với một mô tả, ngay cả khi chỉ có một. Điều này dẫn đến rất nhiều sự lặp lại:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Khi viết tài liệu trong mã, bạn chi tiết đến mức nào?

Để bắt đầu, tôi đồng ý rằng dòng "Hàm:" trong ví dụ của bạn là hoàn toàn dư thừa. Đó cũng là kinh nghiệm của tôi khi mọi người được dạy ở trường thêm loại bình luận đó tiếp tục thêm loại bình luận đó vào mã sản xuất của họ.

Nhận xét tốt không lặp lại những gì trong mã. Họ trả lời câu hỏi "Tại sao?" thay vì "Cái gì?" hoặc thế nào?" Chúng bao gồm các kỳ vọng về các đầu vào, cũng như cách mã sẽ hoạt động trong các điều kiện nhất định. Chúng bao hàm lý do tại sao thuật toán X được chọn thay vì thuật toán Y. Nói tóm lại, chính xác những điều không rõ ràng đối với người khác ¹ khi đọc mã.

^{1: Một người khác quen thuộc với ngôn ngữ mà mã được viết. Đừng viết bình luận để dạy, bình luận để bổ sung thông tin.}

Một số ngôn ngữ có các tính năng tạo tài liệu API như Ruby, Java, C # và C ++ (thông qua một công cụ dòng lệnh). Khi bạn nghĩ về nó theo cách đó, nó làm cho việc viết các tài liệu API quan trọng hơn nhiều. Rốt cuộc, nó trả lời câu hỏi "tôi phải làm thế nào ...?" Vì vậy, tôi sẽ không làm bất cứ điều gì lặp đi lặp lại như Function: MyFunctionkhi tên của hàm rõ ràng cho mọi người thấy. Các công cụ tạo tài liệu API đủ thông minh để làm điều đó cho tôi. Tuy nhiên, các chi tiết sau đây rất hữu ích, đặc biệt là về các phương thức / chức năng công cộng:

• Tóm tắt (những gì nó làm và khi có liên quan tóm tắt về cách sử dụng nó)
• Danh sách các tham số và những gì được mong đợi
• Giá trị trả về (đầu ra) sẽ là bao nhiêu
• Bất kỳ trường hợp ngoại lệ có thể được ném rõ ràng và tại sao

Chúng có thể trở thành các công cụ tham khảo hữu ích khi bạn đang cố gắng gỡ lỗi mã. Nhiều IDE cũng sẽ sử dụng các tài liệu API trong các mẹo công cụ của chúng khi bạn di chuột qua tên hàm.

Nếu đó là một ngôn ngữ không có các tính năng đó, các ý kiến ​​sẽ giúp, nhưng gần như không nhiều.

Nếu đó là một phương thức API công khai thì có, bạn nên cung cấp tài liệu chi tiết, đặc biệt là về các tham số và hành vi dự kiến. Nhiều người cảm thấy rằng điều này có thể được nới lỏng cho các phương thức / chức năng riêng tư, YMMV.

Nhìn chung, tôi thích viết mã sạch (các phương thức / hàm nhỏ làm tốt một việc và một việc) với các tên biến hợp lý. Điều này làm cho nhiều mã của bạn tự viết tài liệu. Tuy nhiên, tôi chắc chắn luôn ghi lại mọi trường hợp cạnh, sử dụng thuật toán đồng thời và thuật toán phức tạp.

Nói tóm lại, hãy nghĩ về bản thân của bạn tệ hơn một chút khi mặc vào lúc 3 giờ sáng vào buổi sáng 3 tháng kể từ bây giờ. Bạn sẽ cảm ơn chính mình vì những tài liệu công cộng tuyệt vời của bạn trái ngược với việc tìm ra tham số nào (cờ boolean) có nghĩa là ...

Điều đó tương tự như cách hầu hết các khung -Doc phân tích tài liệu trong mã (JavaDoc, PHPDoc, v.v.).

Từ Java, được tạo tự động bởi IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Đây là định dạng tương tự được sử dụng để tạo Tài liệu cho các tính năng ngôn ngữ tích hợp - Ví dụ: http://doad.oracle.com/javase/6/docs/api/java/lang/String.html

Định dạng này khá hữu ích vì nó hiển thị rõ ràng cho bất kỳ người dùng bên thứ ba nào về cách giao diện với mã của bạn. Nếu các chức năng của bạn là các phương thức riêng tư chỉ được sử dụng nội bộ, thì điều đó có thể hơi vô nghĩa - nhưng tôi đoán giáo viên của bạn đang cố gắng đưa bạn vào một thực tiễn tốt cho đến khi bạn có kinh nghiệm với việc phân biệt đó.

Bit duy nhất tôi thường thấy hơi dư thừa là mô tả trả về - Thông thường nó gần giống với mô tả phương thức của tôi.

Có hai mục đích cho Nhận xét:

1. Chúng phục vụ để nhắc nhở bạn nhanh chóng những gì mã của bạn làm khi bạn quay lại nó vài tháng / năm sau đó. Bằng cách này, bạn không phải đọc lại và phân tích mã của mình để làm mới bộ nhớ.
2. Họ chuyển tiếp đến những người khác có thể đang đọc hoặc làm việc với mã của bạn những gì mã của bạn đang làm.

Tất nhiên có nhiều NHIỀU cách khác nhau để tiếp cận điều này nhưng bạn càng kỹ lưỡng và nhất quán thì càng tốt. Nhận xét hiệu quả cần có thời gian để học giống như lập trình hiệu quả. Hãy nhớ rằng thật khó để thấy quan điểm nhận xét ở trường vì không có gì bạn đang làm việc đủ lớn để thực sự bảo đảm nhưng họ chỉ đang cố gắng giới thiệu nó với bạn. Và thường thì cách dạy bạn làm theo phong cách giáo sư của bạn chứ không phải bất kỳ loại tiêu chuẩn nào. Phát triển những gì làm việc cho bạn. Và hãy nhớ rằng ... có một thứ như một bình luận ngu ngốc! :) Thí dụ:

a += 1; //adds 1 to the value in a

Có thật không? Cảm ơn! cười lớn

Tôi thích tài liệu từ trang web PHP vì vậy tôi sử dụng một cái gì đó tương tự cho các bình luận nội tuyến của mình và sử dụng cú pháp PHPDoc. Xem ví dụ dưới đây.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

Và giống như @Larry Coleman đã nói, các bình luận nội tuyến sẽ cho biết lý do tại sao bạn đã thực hiện một số đoạn mã.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Nếu đó là dịch vụ của thế hệ Doc thì những bình luận dài dòng (mặc dù khó chịu) có lẽ là một điều tốt. Mặc dù bạn phải biến nó thành mục tiêu của nhóm để luôn đứng đầu các bình luận và cập nhật chúng.

Nếu đó chỉ là phong cách bình luận thì tôi sẽ gặp vấn đề với nó. Nhận xét quá mức có thể làm tổn thương mã cũng như giúp đỡ. Tôi không thể đếm số lần tôi gặp phải các nhận xét trong mã đã hết hạn và dẫn đến sai lệch. Bây giờ tôi thường bỏ qua các bình luận và tập trung vào việc đọc mã và các bài kiểm tra của mã để hiểu nó làm gì và ý định là gì.

Tôi muốn có mã không bình luận rõ ràng súc tích . Cung cấp cho tôi một số bài kiểm tra với các xác nhận hoặc phương pháp mô tả và tôi rất vui và được thông báo.