Suy nghĩ của bạn về Thời gian / Dừng hoàn toàn trong nhận xét mã là gì? [đóng cửa]

Tôi thấy điều này được hỏi trong SO Tavern , vì vậy tôi đang đăng câu hỏi ở đây. Tôi nghĩ đó là một câu hỏi thú vị. (Tất nhiên nó không thuộc về SO, nhưng tôi nghĩ nó ổn ở đây.)

Bạn có thêm dấu chấm (hoặc, như OP đã viết, "dừng hoàn toàn") trong nhận xét mã của bạn không?

Để giữ cho nó có liên quan, tại sao ?

Dừng hoàn toàn là để kết thúc câu, nhưng nếu một bình luận chỉ bao gồm một câu được bao quanh bởi mã, thì theo tôi, toàn bộ dừng lại là không cần thiết. Đôi khi tôi thậm chí không viết hoa chữ cái đầu tiên. Một bình luận multiline chi tiết, mặt khác, không cần chấm câu đầy đủ.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

Có, bởi vì các bình luận bằng tiếng Anh và tiếng Anh thích hợp sử dụng dấu câu.

Bạn có thêm dấu chấm (hoặc, như OP đã viết, "dừng hoàn toàn") trong nhận xét mã của bạn không?

Để giữ cho nó có liên quan, tại sao?

Vì lý do tương tự, tôi thêm chúng khi viết văn bản "bình thường" - chúng là một phần của ngôn ngữ bằng văn bản và không có gì đặc biệt về chúng. Tôi sử dụng chúng như nhau khi viết một câu (một dòng) ý kiến ​​cũng như toàn bộ đoạn văn.

Mã nguồn không phải là văn bản bình thường, và do đó chúng tôi sử dụng các quy tắc khác nhau cho nó. Đơn giản ;-)

Nếu bạn viết bình luận, người ta sẽ hy vọng chúng được viết bằng tiếng Anh. Đó là trường hợp, người ta nên chấm câu đúng. Làm khác đi sẽ lười biếng.

Nếu tôi viết một câu đầy đủ (hoặc nhiều hơn), thì có. Nếu tôi không, thì đôi khi không, nhưng thường vẫn có.

Đôi khi tôi cũng phát điên và sử dụng dấu chấm than, dấu hỏi, v.v.)

Về lý do, đó là một phần vì tôi chỉ đặc biệt như vậy và một phần vì tôi thấy rằng dấu câu phù hợp có thể thêm rất nhiều sự rõ ràng.

Các câu trả lời khác và mức độ phổ biến của chúng đã cho thấy rõ rằng các điểm dừng hoàn toàn được đánh giá cao trong các bình luận dài hơn, và có lẽ có thể tránh được trong một lớp lót.

Một điểm khác có thể có liên quan là tránh dấu chấm than, đặc biệt là bội số . Thí dụ:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

và

    // This code really sucks!

Mặt khác, dấu hỏi đôi khi khá hữu ích:

    // TODO: What does Crojpler.bway() actually do?

Nó phụ thuộc. Nếu tôi viết lên một đoạn văn lớn, phù hợp giải thích những gì một khối mã làm, thì tôi chấm câu đúng, giống như bất kỳ đoạn viết đúng nào khác. OTOH, khi tôi chỉ nhận xét một dòng mã, thì tôi không.

Tại sao? - Tương tự như lý do tại sao tôi viết email bằng cách viết đúng, trong khi tôi có thể sử dụng các câu tốc ký trong tin nhắn SMS. Trong một trường hợp, tôi đang ngồi viết một khối văn bản thích hợp, vì vậy tôi chỉ tự động "làm đúng", trong khi đó, đó chỉ là một ghi chú ngắn gọn để hiểu ý.

Ví dụ thực tế từ mã của tôi:

Ghi chú nhanh:

// check for vk_enter

Tài liệu phương pháp "đúng":

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

Có tôi nghĩ bằng cách này bạn tạo ra một quy ước mã hóa tốt và nó cũng tạo ra một mã dễ đọc cho người thứ 3 xem xét mã của bạn.

Tôi sẽ luôn viết hoa và chấm câu đúng cách khi tạo các nhận xét XML mà tôi mong đợi sẽ được nhìn thấy trong IntelliSense và trong tài liệu được tạo của chúng tôi . Đây là những cấu trúc chính thức hơn nhiều và nên được xử lý như vậy.

Tuy nhiên, các bình luận chỉ nhìn thấy trong phần thân của một khối mã, tuy nhiên, chỉ cần rõ ràng nhất có thể. Tùy thuộc vào lập trình viên cách họ đạt được điều đó.