Tôi đoán những gì tôi đang hỏi là, cách tốt nhất để đảm bảo mã của tôi được ghi chép đầy đủ và diễn đạt đúng cho người khác sử dụng là gì?
Là nguồn mở, các bình luận quan trọng nhất của tất cả là bình luận về bản quyền và thỏa thuận cấp phép. Thay vì một bình luận dài ở đầu mỗi tệp, bạn có thể muốn sử dụng một bình luận ngắn và ngọt, chỉ định ngắn gọn bản quyền và giới thiệu người đọc đến License.txt trong thư mục gốc.
Tôi biết bạn nên luôn nhận xét mọi thứ và tôi sẽ đưa vào tính năng @params cho mọi phương thức, nhưng có bất kỳ mẹo nào khác nói chung không?
Nhận xét mọi thứ? Không. Nhận xét rằng mã thực sự cần bình luận. Bình luận tiết kiệm. Là người dùng tiềm năng của một đoạn mã, hai phiên bản sau của định nghĩa lớp bạn muốn xem là gì?
Phiên bản A:
class Foo {
private:
SomeType some_name; //!< State machine state
public:
...
/**
* Get the some_name data member.
* @return Value of the some_name data member.
*/
SomeType get_some_name () const { return some_name; }
...
};
Phiên bản B:
/**
* A big long comment that describes the class. This class header comment is very
* important, but also is the most overlooked. The class is not self-documenting.
* Why is that class here? Your comments inside the class will say what individual parts
* do, but not what the class as a whole does. For a class, the whole is, or should be,
* greater than the parts. Do not forget to write this very important comment.
*/
class Foo {
private:
/**
* A big long comment that describes the variable. Just because the variable is
* private doesn't mean you don't have to describe it. You might have getters and
* setters for the variable, for example.
*/
SomeType some_name;
public:
...
// Getters and setters
...
// Getter for some_name. Note that there is no setter.
SomeType get_some_name () const { return some_name; }
...
};
Trong phiên bản A tôi đã ghi lại tất cả mọi thứ - ngoại trừ chính lớp đó. Một lớp học nói chung không phải là tài liệu tự. Các ý kiến có trong phiên bản A hoàn toàn vô dụng, hoặc thậm chí tệ hơn vô dụng. Đó là vấn đề chính với thái độ "bình luận mọi thứ". Nhận xét ngắn gọn đó về thành viên dữ liệu riêng tư không liên lạc gì và các bình luận doxygen trên getter có giá trị âm. Các getter get_some_name()không thực sự cần một bình luận. Những gì nó làm và những gì nó trả lại là rõ ràng từ mã. Rằng không có setter - bạn phải suy luận rằng vì nó không có ở đó.
Trong phiên bản B tôi đã ghi lại rằng cần bình luận. Các getter không có một bình luận doxygen, nhưng nó có một bình luận đề cập rằng không có setter.
Làm cho ý kiến của bạn được tính và hãy cẩn thận rằng các bình luận thường không được duy trì để phản ánh các thay đổi đối với mã.