Nhận xét trước hoặc sau mã liên quan [đã đóng]

Giả sử một bình luận sẽ không phù hợp (hoặc không thể đi) trên dòng mà nó áp dụng, nên viết bình luận trước mã hay sau?

Vâng, bất cứ nơi nào độc giả trong tương lai sẽ hiểu rõ nhất phạm vi bình luận. Nói cách khác, bất cứ nơi nào hầu hết các lập trình viên / người viết kịch bản đều đưa ra những nhận xét như vậy.

Vì vậy , hầu hết các lập trình viên / người viết kịch bản đưa ra một nhận xét: trước hoặc sau mã của nó?

Nếu câu trả lời của bạn chỉ áp dụng cho các ngôn ngữ cụ thể, vui lòng cho biết.

Và nếu bạn có thể trích dẫn một thông số hoặc hướng dẫn được chấp nhận hỗ trợ câu trả lời của bạn, thì càng nhiều càng tốt.

Tôi sẽ bình luận nội tuyến hoặc trước mã mà bình luận nên áp dụng. Ý nghĩa của các bình luận là để có được một số hiểu biết cơ bản về những gì mã làm, mà không cần phải đọc mã. Vì vậy, nó có ý nghĩa hơn nhiều để đặt các ý kiến ​​trước mã mà nó mô tả.

Microsoft nói rằng nó sẽ là một thực hành lập trình tốt để bắt đầu các thủ tục với một nhận xét nhỏ. (Họ không đề cập đến việc bình luận sau các thủ tục) MSDN Liên kết là về VisualBasic nhưng nó áp dụng cho hầu hết các ngôn ngữ lập trình mà tôi nghĩ.

Tôi thích các bình luận ở trên mã mà họ đề cập, sẽ hợp lý hơn khi nói với một người đang đọc mã về những gì sắp xảy ra thay vì cố gắng tham khảo mã trước đó để giải thích rằng một số dòng mã lộn xộn đã sửa một số lỗi khó hiểu vì vậy đừng chạm vào nó

Tôi nghĩ rằng mã thường được đọc từ trên xuống dưới. Nếu không có gì khác, bộ nhớ cơ sẽ khiến tôi liên kết một bình luận với dòng mã tiếp theo bên dưới nó.

Thông thường, bình luận phải ở trên TOP của hàng sau cùng một vết lõm như tác phẩm. Ví dụ, các bình luận phía trên phần thân của các hàm và một bình luận lót ngay phía trên phần bắt đầu của một thuật toán quan trọng.

Lý do là, khi ai đó bắt đầu đọc nó, nó trở thành câu hỏi rõ ràng rằng tại sao một cái gì đó được thực hiện theo cách như vậy; khi mà người đó không biết cho đến khi nào người ta cần cuộn câu trả lời. Nếu nó ở trên, nó ở ngay đó để xem.

Vì vậy, hầu hết các lập trình viên / người viết kịch bản đưa ra một nhận xét: trước hoặc sau mã của nó?

Trong nhiều năm lập trình sử dụng nhiều ngôn ngữ khác nhau, tôi không nhớ đã thấy bất kỳ mã nào trong bất kỳ ngôn ngữ nào có nhận xét được đặt trên một dòng mới sau mã mà nó đề cập đến. Ở Mỹ, ít nhất, tiêu chuẩn thực tế đang bình luận trước mã hoặc trên cùng một dòng theo mã. Viết bình luận của bạn sau khi mã liên quan mời thử nghiệm ma túy, đánh giá tâm thần và / hoặc hẹn hò với một cặp kìm và đèn khò.

Ngoại lệ duy nhất tôi có thể nghĩ đến là một bình luận đánh dấu sự kết thúc của phần bình luận trước đó, như thế này:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin đã viết một bài luận được đánh giá tốt về các bình luận đáng đọc. Anh ta không nói liệu anh ta có đưa ra nhận xét của mình trước hay sau mã hay không, nhưng anh ta nói rằng anh ta không bao giờ đặt chúng nội tuyến, và tôi đặt cược rất nhiều tiền mà anh ta không đặt chúng sau đó.

Cố gắng chỉ nhận xét khi thực sự cần thiết; mã nên cố gắng tự ghi lại bất cứ khi nào có thể.

Điều đó đang được nói, vị trí có thể phụ thuộc: Nếu bạn sử dụng một dòng riêng cho nhận xét, hãy đặt nó trước mã thực tế. Nếu bạn có nó trên cùng một dòng, đặt nó sau.

// this workaround is required to make the compiler happy
int i = 0;

Vs

int i = 0; // make the compiler happy

Nhưng không bao giờ:

int i = 0;
// this workaround is required to make the compiler happy

Tôi không thực sự là một fan hâm mộ lớn của ý kiến. Trong một khóa học về kỹ thuật phần mềm, tôi đã được giới thiệu về ý tưởng tự viết mã. Mã này là tài liệu chính xác duy nhất được đảm bảo 100% của chính nó - các bình luận cần được cập nhật, xây dựng cẩn thận và có liên quan, nếu không chúng là những cái bẫy có thể tồi tệ hơn không có bình luận. Mãi cho đến khi tôi bắt đầu làm việc trong một cửa hàng C ++ với một hướng dẫn phong cách nghiêm ngặt và những quy ước đặt tên có ý nghĩa mà tôi thực sự nội tâm hóa khái niệm này.

Đôi khi ý kiến ​​là cần thiết. Rất nhiều lần, việc đặt tên biến cẩn thận, sử dụng có ý nghĩa của khoảng trắng và nhóm, và một tổ chức logic có ý nghĩa của chính mã đã loại bỏ sự cần thiết của nhận xét.

Đây thực sự là một sự phủ nhận về sự giả vờ và tính hợp lệ của câu hỏi của bạn, trái ngược với câu trả lời cho câu hỏi bạn có. Tôi vẫn nghĩ rằng nó có liên quan và có thể giúp bạn, và tôi không phải là một kẻ ngốc. Nếu không, -1 sẽ thống trị tôi.

Có nhận xét xuất hiện trước khi mã giúp người đọc có bối cảnh cho mã mà họ sắp gặp phải. Nhân văn hơn nhiều so với việc ném mã vào họ và giải thích sau khi họ đã bối rối.

OK, tôi sẽ tạo trường hợp "sau": mã phải luôn là tài liệu chính, trong khi nhận xét (không có ý nghĩa ngữ nghĩa) giống như một lời giải thích mang tính phụ huynh. Vì vậy, đặt bình luận bên dưới mã cần giải thích để lại mã làm giải thích chính và chỉ sử dụng nhận xét để làm rõ. Ví dụ,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

Nếu bạn đặt bình luận trước khi kiểm tra, người đọc sẽ có xu hướng đọc bình luận là điều chính và có thể không đọc mã chặt chẽ, không nhận ra rằng họ đã bị đánh lừa:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

Để mượn một số ý tưởng từ văn bản kỹ thuật (ít nhất là bằng tiếng Anh), những thứ như ghi chú và cảnh báo thận trọng thường được đặt trước hướng dẫn hoặc phần mà ghi chú hoặc cảnh báo thận trọng áp dụng.

Tôi không thấy lý do tại sao mã không thể được coi là một hình thức viết kỹ thuật - mỗi khối là một hướng dẫn. Giống như ngôn ngữ tiếng Anh, hầu hết các ngôn ngữ lập trình được đọc từ trái sang phải, từ trên xuống dưới. Nhận xét là ghi chú về mã - họ có thể xác định lỗi để sửa hoặc những điều mà nhà phát triển trong tương lai có thể cần phải biết.

Theo mối quan hệ này, có vẻ thích hợp hơn để đặt bình luận trên khối mã mà nó đề cập đến.

Một nhận xét có thể cần phải đi trên hoặc dưới một đoạn mã, tùy thuộc vào loại bình luận đó là gì: nếu nó đưa ra một lời giải thích cực kỳ ngắn gọn về những gì mã làm, thì nó cần phải đi trước mã; nếu nó làm rõ một cách chi tiết kỹ thuật về cách thức hoạt động của mã, thì nó cần phải tuân theo mã.

May mắn thay, một nhận xét có thể đi lên trên hoặc bên dưới một đoạn mã, và vẫn không có nghi ngờ gì về đoạn mã nào liên quan đến nó, bằng cách sử dụng đúng các dòng trống. Tất nhiên, các lập trình viên không chú ý đến việc sử dụng các dòng trống sẽ không biết tôi đang nói về cái gì; nếu bạn là một trong số đó, xin vui lòng bỏ qua câu trả lời này và tiếp tục cuộc sống của bạn. Nhưng các lập trình viên chú ý đến các dòng trống biết rất rõ rằng các dòng trống được sử dụng để phân chia mã thành các thực thể logic. Vì vậy, nếu bạn thấy như sau:

[blank line]
/* comment */
{ code }
[blank line]

Bạn biết rằng nhận xét thuộc về mã và nó cho bạn biết mã đó làm gì. Trong khi đó, nếu bạn thấy như sau:

[blank line]
{ code }
/* comment */
[blank line]

Một lần nữa bạn biết rất rõ rằng bình luận thuộc về mã đó, và nó là một sự làm rõ về cách mã thực hiện những gì nó làm.

Nhận xét trên là tốt nhất.

nếu bạn phải bao gồm các bình luận và mã của bạn không tự giải thích được, thì tôi không muốn bị nhầm lẫn bởi một khối mã, sau đó xem "ahh, đó là những gì nó phải làm".

Mã có thể (và nên) là "tự viết tài liệu", nhưng nếu bạn phải đọc và hiểu từng dòng mã để hiểu cách thức hoạt động của một phương thức. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Khi tôi tìm hiểu về chủ đề này, tôi thấy rằng hầu hết các hệ thống tài liệu có thể đọc được trên máy tính (Doc XML, Doxygen, Java doc, v.v.) mong nhận xét sẽ xuất hiện trước mã mà nó liên quan - tốt hơn là vẫn tương thích với tiêu chuẩn đó.

Tôi cũng đồng ý với chủ đề SO - Chúng ta có nên thêm nhận xét sau các khối mã, thay vì trước đó không? ..

Tôi cũng muốn biết trước ...

Tôi thường chuyển đổi các bình luận (của tôi cũng như được viết bởi người khác) thành các báo cáo nhật ký mức theo dõi. Điều này thường làm cho nó dễ dàng hơn nhiều để hiểu nơi đặt nó.

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

Một lợi thế nữa là khi gặp khó khăn tôi có thể bật theo dõi nhật ký và nhận nhật ký thực hiện chi tiết hơn.