Tôi muốn nghe từ bạn bất kỳ lời khuyên và kinh nghiệm viết bình luận trong mã của bạn. Làm thế nào để bạn viết chúng theo cách dễ dàng và nhiều thông tin nhất? Những thói quen nào bạn có khi bình luận các phần của mã? Có thể một số khuyến nghị kỳ lạ?

Tôi hy vọng câu hỏi này sẽ thu thập những lời khuyên và khuyến nghị thú vị nhất, một điều hữu ích mà mọi người đều có thể học hỏi.

Được, tôi sẽ bắt đầu.

1. Thông thường, tôi không sử dụng /* */bình luận ngay cả khi tôi cần bình luận nhiều dòng.

   Ưu điểm : mã trực quan trông tốt hơn so với khi bạn trộn cú pháp như vậy với các nhận xét một dòng. Hầu hết các IDE có khả năng nhận xét văn bản đã chọn và họ thường làm điều đó với cú pháp một dòng.

   Nhược điểm : Khó chỉnh sửa mã như vậy mà không có IDE.

2. Đặt "dấu chấm" vào cuối của bất kỳ bình luận đã hoàn thành.

   Ví dụ:

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   Ưu điểm : Chỉ đặt "dấu chấm" trong các bình luận mà bạn đã hoàn thành. Đôi khi bạn có thể viết thông tin tạm thời, vì vậy thiếu "dấu chấm" sẽ cho bạn biết rằng bạn muốn quay lại và thêm một số văn bản bổ sung vào nhận xét này.

3. Căn chỉnh văn bản trong bảng liệt kê, tham số bình luận, vv

   Ví dụ:

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   Ưu điểm : Chỉ cần nhìn tốt hơn và trực quan dễ dàng hơn để tìm thấy những gì bạn cần.

   Nhược điểm : Dành thời gian để căn chỉnh và khó chỉnh sửa hơn.

4. Viết văn bản trong bình luận mà bạn không thể có được bằng cách phân tích mã.

   Ví dụ, bình luận ngu ngốc:

   //Apply style.
   Apply(style);
   

   Ưu điểm : Bạn sẽ có mã rõ ràng và nhỏ chỉ với thông tin hữu ích trong các bình luận.

Một số tuyên bố dưới đây khá cá nhân, mặc dù với một số biện minh, và có nghĩa là theo cách này.

Các loại bình luận

Đối với phiên bản ngắn gọn ... Tôi sử dụng nhận xét cho:

• theo dõi các bình luận giải thích các trường trong cấu trúc dữ liệu (ngoài các trường đó, tôi không thực sự sử dụng các nhận xét dòng đơn)
• nhận xét nhiều dòng đặc biệt hoặc theo mục đích trên các khối
• tài liệu người dùng công cộng và / hoặc nhà phát triển được tạo từ nguồn

Đọc dưới đây để biết chi tiết và (có thể tối nghĩa) lý do.

Nhận xét

Tùy thuộc vào ngôn ngữ, sử dụng nhận xét một dòng hoặc nhận xét nhiều dòng. Tại sao nó phụ thuộc? Đó chỉ là một vấn đề tiêu chuẩn hóa. Khi tôi viết mã C, tôi thích mã ANSI C89 kiểu cũ theo mặc định, vì vậy tôi thích luôn luôn có /* comments */.

Do đó, tôi sẽ có phần này trong C hầu hết thời gian và đôi khi (phụ thuộc vào kiểu của cơ sở mã) cho các ngôn ngữ có cú pháp giống như C:

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs là tốt đẹp và làm điều đó cho tôi với M-;.

Nếu ngôn ngữ hỗ trợ nhận xét một dòng và không dựa trên C, tôi sẽ được bao bọc nhiều hơn để sử dụng các nhận xét một dòng. Nếu không, tôi sợ bây giờ tôi đã có thói quen. Điều này không hẳn là xấu, vì nó buộc tôi phải súc tích.

Nhận xét nhiều dòng

Tôi không đồng ý với giới luật của bạn bằng cách sử dụng các nhận xét một dòng cho điều này hấp dẫn trực quan hơn. Tôi sử dụng cái này:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

Hoặc đây (nhưng tôi không thường nữa, ngoại trừ trên một codebase cá nhân hoặc chủ yếu để thông báo bản quyền - đây là lịch sử đối với tôi và xuất phát từ nền giáo dục của tôi Thật không may, hầu hết các IDEs vít nó lên khi sử dụng tính năng tự động định dạng.) :

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

Nếu cần thực sự, sau đó tôi sẽ bình luận nội tuyến bằng cách sử dụng những gì tôi đã đề cập trước đó cho các bình luận theo dõi, nếu nó có ý nghĩa để sử dụng nó trong một vị trí theo dõi. Ví dụ, trong trường hợp trả lại rất đặc biệt hoặc để ghi lại switchcác casecâu lệnh (hiếm gặp, tôi không sử dụng công tắc thường xuyên) hoặc khi tôi ghi lại các nhánh trong if ... elseluồng điều khiển. Nếu đó không phải là một trong số này, thường thì một khối nhận xét nằm ngoài phạm vi phác thảo các bước của hàm / phương thức / khối có ý nghĩa hơn đối với tôi.

Tôi sử dụng những thứ này rất đặc biệt, trừ khi mã hóa bằng ngôn ngữ mà không hỗ trợ cho nhận xét tài liệu (xem bên dưới); trong trường hợp họ trở nên phổ biến hơn. Nhưng trong trường hợp chung, nó thực sự chỉ để ghi lại những thứ dành cho các nhà phát triển khác và là những bình luận nội bộ thực sự cần phải thực sự nổi bật. Chẳng hạn, để ghi lại một khối trống bắt buộc như khối "bắt buộc" catch:

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

Điều này đã xấu đối với tôi nhưng tôi sẽ chịu đựng trong một số trường hợp.

Bình luận tài liệu

Javadoc & al.

Tôi thường sử dụng chúng trên các phương thức và lớp để ghi lại các phiên bản giới thiệu một tính năng (hoặc thay đổi nó) đặc biệt nếu đó là API công khai và để cung cấp một số ví dụ (với các trường hợp đầu vào và đầu ra rõ ràng và các trường hợp đặc biệt). Mặc dù trong một số trường hợp, một trường hợp đơn vị có thể tốt hơn để ghi lại những điều này, các bài kiểm tra đơn vị không nhất thiết phải là con người có thể đọc được (cho dù bạn sử dụng DSL-thingy nào).

Họ sửa lỗi cho tôi một chút để ghi lại các trường / thuộc tính, vì tôi thích các bình luận theo dõi cho điều này và không phải tất cả các khung tạo tài liệu đều hỗ trợ các bình luận tài liệu theo dõi. Doxygen chẳng hạn, nhưng JavaDoc thì không, điều đó có nghĩa là bạn cần một nhận xét hàng đầu cho tất cả các lĩnh vực của mình. Mặc dù vậy, tôi có thể tồn tại điều đó, vì dù sao đi nữa, các dòng Java tương đối dài, do đó, một nhận xét kéo dài sẽ làm tôi khó chịu bằng cách mở rộng dòng vượt quá ngưỡng chịu đựng của tôi. Nếu Javadoc từng cân nhắc việc cải thiện điều đó, thì tôi sẽ hạnh phúc hơn rất nhiều.

Mã nhận xét

Tôi chỉ sử dụng một dòng cho một lý do duy nhất, bằng các ngôn ngữ giống như C (trừ khi biên dịch cho C nghiêm ngặt, nơi tôi thực sự không sử dụng chúng): để bình luận nội dung trong khi mã hóa. Hầu hết các IDE sẽ phải chuyển đổi các nhận xét một dòng (được căn chỉnh trên thụt lề hoặc trên cột 0) và phù hợp với trường hợp sử dụng đó đối với tôi. Sử dụng chuyển đổi cho các nhận xét nhiều dòng (hoặc chọn ở giữa các dòng, đối với một số IDE) sẽ khiến việc chuyển đổi giữa nhận xét / không chú ý trở nên khó khăn hơn.

Nhưng vì tôi chống lại mã nhận xét trong SCM, điều đó thường tồn tại rất ngắn vì tôi sẽ xóa các đoạn bình luận trước khi cam kết. (Đọc câu trả lời của tôi cho câu hỏi này về "các bình luận và SCMs được chỉnh sửa" )

Bình luận kiểu

Tôi thường có xu hướng viết:

• hoàn thành các câu với ngữ pháp chính xác (bao gồm cả dấu câu) để nhận xét tài liệu, vì chúng được cho là sẽ được đọc sau trong tài liệu API hoặc thậm chí là một phần của hướng dẫn được tạo.
• được định dạng tốt nhưng lỏng lẻo hơn về dấu câu / mũ cho khối nhận xét nhiều dòng
• khối theo dõi mà không có dấu chấm câu (vì không gian và thường vì nhận xét là ngắn gọn, đọc giống như một câu lệnh được ngoặc đơn)

Một lưu ý về lập trình biết chữ

Bạn có thể muốn có hứng thú với Lập trình biết chữ , như được giới thiệu trong bài viết này của Donald Knuth .

Mô hình lập trình biết chữ, [...] thể hiện sự tránh xa việc viết chương trình theo cách thức và trật tự được áp đặt bởi máy tính, và thay vào đó cho phép các lập trình viên phát triển các chương trình theo yêu cầu logic và dòng chảy suy nghĩ của họ. 2 Các chương trình biết chữ được viết như một sự giải thích logic không bị gián đoạn trong một ngôn ngữ thông thường của con người, giống như văn bản của một bài tiểu luận [...].

Các công cụ lập trình biết chữ được sử dụng để có được hai biểu diễn từ tệp nguồn biết chữ: một công cụ phù hợp để biên dịch hoặc thực thi thêm bằng máy tính, mã "rối" và một cách khác để xem dưới dạng tài liệu được định dạng, được cho là "dệt" từ nguồn biết chữ.

Như một lưu ý phụ và ví dụ: Khung JavaScript underscore.js , mặc dù không tuân thủ phong cách nhận xét của tôi, là một ví dụ khá hay về một cơ sở mã tài liệu tốt và một nguồn chú thích được định dạng tốt - mặc dù có thể không sử dụng tốt nhất như một tài liệu tham khảo API).

Đây là những quy ước cá nhân . Vâng, tôi có thể là lạ (và bạn cũng có thể như vậy). Không sao, miễn là bạn tuân thủ và tuân thủ các quy ước về mã của nhóm của bạn khi làm việc với các đồng nghiệp, hoặc không tấn công triệt để sở thích của họ và sống chung một cách độc đáo. Đó là một phần trong phong cách của bạn và bạn nên tìm ra ranh giới giữa việc phát triển một phong cách mã hóa xác định bạn là một lập trình viên (hoặc là người theo trường phái tư tưởng hoặc tổ chức mà bạn có kết nối) và tôn trọng sự thống nhất của một nhóm .

Khi tôi đi học đại học, tôi luôn được dạy để bình luận mọi dòng mã và mọi tiêu đề phương thức. Nó đã được đánh trống trong / truyền đạt đến mức mà bạn đã làm điều đó mà không có câu hỏi. Đã từng là thành viên của một số nhóm phát triển Agile tại các công ty khác nhau, tôi có thể nói rằng tôi có thể viết bình luận một lần trong một mặt trăng xanh.

Lý do cho điều này là hai lần, trước hết chúng ta không nên viết các phương thức nguyên khối dài mà thực hiện 101 điều khác nhau, tên lớp, phương thức và biến nên tự ghi lại. Lấy phương thức đăng nhập sau đây làm ví dụ.

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

Điều này có thể được viết lại thành một cái gì đó dễ đọc hơn và có thể tái sử dụng:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

Bạn có thể thấy rõ từ phương thức đăng nhập những gì đang diễn ra. Bạn có thể xem đây là công việc làm thêm nhưng phương pháp của bạn nhỏ và chỉ có một công việc. Ngoài ra, tên phương thức là mô tả nên không cần phải viết bất kỳ nhận xét tiêu đề phương thức nào. Nếu bạn kết thúc với quá nhiều phương thức thì đây là dấu hiệu cho thấy các phương thức liên quan nên được đưa vào lại thành một đối tượng khác, chẳng hạn như UserAuthenticationService, hãy nhớ một đối tượng chỉ nên có một công việc.

Thứ hai, mỗi đoạn mã mà bạn viết, bao gồm cả các bình luận, phải được duy trì, bạn càng có nhiều bình luận thì càng có nhiều thứ để duy trì. Nếu bạn đổi tên một lớp hoặc một biến, bạn sẽ gặp lỗi biên dịch nhưng nếu bạn thay đổi cách một phần mã hoạt động hoặc xóa nó và không cập nhật bất kỳ nhận xét liên quan nào thì sẽ không có lỗi biên dịch và các bình luận sẽ bị treo gây nhầm lẫn .

Nếu bạn đang viết một API thì tôi tin rằng bất kỳ giao diện, lớp nào, các bảng liệt kê phải có các nhận xét tiêu đề được viết tốt cho tài liệu.

Tập trung ít hơn vào định dạng và nhiều hơn vào nội dung. Ví dụ, các ý kiến ​​trong ví dụ của bạn cho tôi biết không có gì mới. Chúng tồi tệ hơn vô giá trị khi chúng làm mất khả năng đọc mã, và những bình luận như thế này tốt nhất là một tài liệu tham khảo mơ hồ về những gì lập trình viên ban đầu nghĩ rằng anh ta đang làm vào thời điểm anh ta viết nó. Tôi có thể thấy từ ví dụ mã mà bạn đang áp dụng một kiểu "áp dụng (Kiểu)", tôi có thể đọc nguồn. Tôi không thể đọc được suy nghĩ của bạn, - tại sao bạn làm điều đó là những gì bình luận nên nói với tôi. ví dụ hơn là

//Apply style.

Apply(style);

nên là

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

Hầu hết chúng ta làm việc theo nhóm theo mã hiện có, định dạng cách các thành viên còn lại làm theo cách mà nó đã được thực hiện. Tính nhất quán quan trọng hơn nhiều so với xinh đẹp.

Càng nhiều càng tốt, viết mã của bạn sao cho các bình luận sẽ hoàn toàn không liên quan. Chỉ thêm nhận xét khi mã không thể được viết theo cách mà nó sẽ làm cho một khái niệm quan trọng trở nên rõ ràng.

Sở thích riêng của tôi là giữ cho nó thực sự đơn giản. Tôi tránh tất cả các loại định dạng ưa thích. Lý do chính cho điều này là tôi nghĩ rằng mã nguồn nên có thể chỉnh sửa thoải mái với ngay cả trình soạn thảo văn bản đơn giản nhất. Tôi cũng không bao giờ cứng các đoạn văn bản mà thay vào đó hãy để trình soạn thảo thực hiện gói mềm (không thêm dòng mới).

Tôi thường thấy những bình luận như vậy và một số công cụ tự động tạo ra nó theo cách đó:

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

Hai dòng ít hơn:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

IDE và Trình chỉnh sửa, nhỉnh hơn mức notepad, có thể phát hiện các bình luận và in chúng bằng một màu khác. Không cần phải trang trí đầu dòng bằng dấu hoa thị.

Bạn thậm chí còn dự phòng một số byte, nếu bạn sử dụng một tab để thụt lề.

Nếu bạn không sử dụng một trình soạn thảo tinh vi, thể hiện nhận xét bằng tông màu xám, một lượng lớn các dấu sao sẽ hoạt động như một điểm nhấn và thu hút sự chú ý của bạn, điều ngược lại với điều đúng đắn phải làm: ở lại phía sau.

Đây là một "chống mẫu" mà tôi đã tìm thấy trong toàn bộ mã công việc của mình: Việc sử dụng các nhận xét làm "nhật ký thay đổi"; đó là những gì nhật ký trong hệ thống kiểm soát phiên bản của bạn dành cho. Mã được rải rác với những thứ như:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

và thường bao gồm mã cũ đã được nhận xét (một lần nữa, đó là điểm của hệ thống VCS vì vậy không cần phải có mã sau khi mã mới được viết). Ngoài ra một điều cần tránh là những bình luận lặp đi lặp lại như "Tại sao chúng ta cần điều này?" hoặc tệ hơn nữa là "Điều này có lẽ nên được đổi tên" (vì có những công cụ tinh vi để đổi tên, vì vậy trong thời gian bạn phải viết nhận xét đó, bạn có thể đổi tên điều đó). Một lần nữa, tôi xử lý cả hai bình luận đó một cách thường xuyên, dọc theo dòng:

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. Chọn một hệ thống tài liệu như doxygen và gắn bó với nó. Tiếp tục kiểm tra các tài liệu được sản xuất.
2. Hãy thử hình dung ai đó mới đến cơ sở mã đến và đọc tài liệu của bạn, họ có thể bắt đầu chạy với nó không? Thực tập sinh thực sự tốt cho điều đó, ngồi xuống một cơ sở mới với cơ sở tài liệu hiện có của bạn và một nhiệm vụ đơn giản và xem họ đi được bao xa, nếu họ vấp ngã, chắc chắn bất cứ điều gì bạn nói với họ để họ tiếp tục đi vào tài liệu.
3. Làm cho tài liệu nhận xét một điểm kiểm tra trong quá trình xem xét của bạn.

Người đọc mã thường cố gắng trả lời ba câu hỏi:

1. Lớp hoặc chức năng này làm gì? Nếu điều này khó trả lời, thì nó làm quá nhiều. Mã khó tài liệu thường chỉ là sai.
2. Làm thế nào để tôi sử dụng nó? Một ví dụ có thể là đủ tốt.
3. Mã đó là đáng ngạc nhiên. Tại sao bạn làm vậy? Các câu trả lời rất có thể: khắc phục lỗi trong các thành phần của bên thứ ba, vì kỹ thuật rõ ràng đã được chứng minh là quá chậm

Mọi thứ khác nên được thể hiện trong mã. Giống như viết văn xuôi, đây là một nghệ thuật, và cần rất nhiều thực hành. Cách duy nhất để biết mã của bạn có dễ hiểu hay không là nhờ người khác đọc nó. Khi họ không hiểu điều gì đó, đừng giải thích nó bằng lời nói. Cải thiện mã. Thêm ý kiến ​​như là một phương sách cuối cùng.

Nếu tôi thấy "chiều dài gấp đôi" tôi sẽ hỏi "Đơn vị đo là gì?" Đừng thêm một bình luận. Thay đổi tên biến. Nếu tôi thấy một khối mã và tôi nói "việc này làm gì?", Đừng thêm nhận xét. Trích xuất một hàm với một tên có ý nghĩa. Nếu bạn không thể trích xuất một hàm vì nó sẽ cần 17 đối số, sau đó cấu trúc lại mã.