Nhận xét là một mã mùi

Một đồng nghiệp của tôi tin rằng bất kỳ việc sử dụng nhận xét trong mã nào (nghĩa là không phải phương thức kiểu javadoc hoặc nhận xét lớp) là mùi mã . Bạn nghĩ sao?

Chỉ khi nhận xét mô tả những gì mã đang làm.

Nếu tôi muốn biết những gì đang xảy ra trong một phương thức hoặc khối, tôi sẽ đọc mã. Dù sao, tôi hy vọng rằng bất kỳ nhà phát triển nào làm việc trong một dự án nhất định ít nhất cũng đủ quen thuộc với ngôn ngữ phát triển để đọc những gì được viết và hiểu những gì nó đang làm.

Trong một số trường hợp tối ưu hóa cực độ, bạn có thể đang sử dụng các kỹ thuật khiến ai đó khó theo dõi những gì mã của bạn đang làm. Trong những trường hợp này, các bình luận có thể và nên được sử dụng để không chỉ giải thích lý do tại sao bạn có tối ưu hóa như vậy, mà cả mã đang làm gì. Một nguyên tắc tốt là sẽ có người khác (hoặc nhiều người khác) làm quen với ngôn ngữ triển khai và dự án xem mã của bạn - nếu họ không thể hiểu cả lý do và cách thức, thì bạn nên bình luận cả lý do và Làm thế nào.

Tuy nhiên, những gì không rõ ràng trong mã là lý do tại sao bạn đã làm một cái gì đó. Nếu bạn thực hiện một cách tiếp cận có thể không rõ ràng với người khác, bạn nên có một nhận xét giải thích lý do tại sao bạn đưa ra quyết định mà bạn đã làm. Tôi nghi ngờ rằng bạn thậm chí có thể không nhận ra rằng cần có một nhận xét cho đến sau khi một cái gì đó giống như đánh giá mã, nơi mọi người muốn biết lý do tại sao bạn làm X thay vì Y - bạn có thể ghi lại câu trả lời của mình cho người khác xem nó trong tương lai.

Tuy nhiên, điều quan trọng nhất là thay đổi nhận xét của bạn khi bạn thay đổi mã. Nếu bạn thay đổi một thuật toán, hãy chắc chắn cập nhật các nhận xét với lý do tại sao bạn đi với thuật toán X trên Y. Nhận xét cũ là một mùi mã thậm chí còn lớn hơn.

Điều này đặc biệt khó chịu khi nghe vào lúc này, tôi đã dành một chút thời gian vào cuối tuần này để xem mã rất nổi tiếng, rất sạch sẽ, không bị lỗi khi thực hiện một thuật toán nghiên cứu (một thuật toán chưa được công bố thực sự). Tôi cấp cao quen thuộc với nó, anh chàng ngồi cạnh tôi là nhà phát minh và mã được viết bởi một vài năm trước bởi một người khác. Chúng tôi hầu như không thể làm theo nó.

Đồng nghiệp của bạn không đủ kinh nghiệm, rõ ràng.

Bình luận nên giải thích tại sao chứ không phải như thế nào.

Howloại bình luận thường được xử lý tốt hơn với việc sử dụng tái cấu trúc. Cá nhân, tôi thường tránh bình luận ủng hộ tái cấu trúc.

Trước:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

sau:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

Tôi tuyên bố đồng nghiệp của bạn là một kẻ dị giáo! Những đôi giày heretic-burnin 'của tôi đâu rồi?

Nhận xét ám ảnh là xấu và đau đầu bảo trì, và bình luận không thể thay thế cho các phương thức, lớp, biến được đặt tên tốt, v.v. Nhưng đôi khi đặt ra lý do tại sao một cái gì đó lại có thể vô cùng quý giá đối với kẻ ngốc nghèo phải duy trì mã trong sáu tháng - đặc biệt là khi tên ngốc đáng thương đó trở thành bạn.

Một số ý kiến ​​thực tế từ mã tôi đang làm việc:

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

Lý tưởng nhất, mã phải được mã hóa tốt đến mức nó phải tự động khám phá. Trong thế giới thực, chúng ta biết rằng mã cũng rất cần chất lượng đôi khi cần bình luận.

Điều bạn tuyệt đối nên tránh là "dự phòng mã nhận xét" (những bình luận không thêm bất cứ điều gì vào mã):

i++; // Increment i by 1

Sau đó, nếu có một tài liệu và thiết kế mã tốt (và được duy trì / căn chỉnh), việc bình luận thậm chí còn ít hữu ích hơn.

Nhưng trong một số trường hợp, các bình luận có thể là một trợ giúp tốt về khả năng đọc mã:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

Đừng quên rằng bạn phải duy trì và giữ đồng bộ các bình luận ... bình luận lỗi thời hoặc sai có thể là một nỗi đau khủng khiếp! Và, như một quy luật chung, bình luận quá nhiều có thể là một triệu chứng của lập trình xấu.

Phân loại xác định một phương pháp hoặc quy trình như một "mùi mã" là "mùi nhiệt tâm". Thuật ngữ này đang trở thành "được coi là có hại" mới.

Xin nhớ rằng tất cả những thứ này được cho là hướng dẫn.

Nhiều câu trả lời khác đưa ra lời khuyên tốt khi bình luận được bảo hành.

Cá nhân tôi sử dụng rất ít ý kiến. Giải thích mục đích của các quá trình không rõ ràng và để lại mối đe dọa tử vong thường xuyên cho bất kỳ ai có thể đang cân nhắc thay đổi mọi thứ theo cách riêng của họ trong vài tuần điều chỉnh.

Tái cấu trúc mọi thứ cho đến khi một học sinh mẫu giáo có thể hiểu rằng đó có thể không phải là cách sử dụng hiệu quả thời gian của bạn và có thể sẽ không hoạt động tốt như một phiên bản ngắn gọn hơn.

Nhận xét không ảnh hưởng đến thời gian chạy, vì vậy vấn đề tiêu cực duy nhất cần xem xét là bảo trì.

Trong một số trường hợp, không có số lượng đặt tên tốt, tái cấu trúc, vv có thể thay thế một nhận xét. Chỉ cần nhìn vào ví dụ thực tế này (ngôn ngữ là Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Trông lạ nhỉ? Có lẽ là một lỗi sao chép-dán? Tiếng khóc cho một lỗi?

Bây giờ giống nhau với ý kiến:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

Vấn đề chính ở đây là ý nghĩa của thuật ngữ "mùi mã".

Nhiều người (bao gồm cả bạn, tôi nghĩ) hiểu một mùi mã là một cái gì đó gần với một lỗi hoặc ít nhất là một cái gì đó cần phải được sửa chữa. Có lẽ bạn nghĩ về nó như một từ đồng nghĩa với "chống mẫu".

Đây không phải là ý nghĩa của thuật ngữ!

Ẩn dụ mùi mã bắt nguồn từ Wards Wiki và họ nhấn mạnh:

Lưu ý rằng CodeSmell là một gợi ý rằng có thể có gì đó không đúng, không chắc chắn. Một thành ngữ hoàn toàn tốt có thể được coi là CodeSmell vì nó thường bị sử dụng sai hoặc vì có một cách thay thế đơn giản hơn, hoạt động trong hầu hết các trường hợp. Gọi một cái gì đó là CodeSmell không phải là một cuộc tấn công; nó chỉ đơn giản là một dấu hiệu cho thấy một cái nhìn gần hơn được bảo hành.

Vì vậy, ý nghĩa của các bình luận là mùi mã: có nghĩa là khi bạn nhìn thấy một bình luận, bạn nên tạm dừng và nghĩ: "Hmmm, tôi cảm thấy một gợi ý rằng một cái gì đó có thể được cải thiện". Có lẽ bạn có thể đổi tên một biến, thực hiện "phương pháp trích xuất" - tái cấu trúc - hoặc có lẽ nhận xét thực sự là giải pháp tốt nhất.

Đó là những gì nó có nghĩa là cho ý kiến ​​là mã mùi.

EDIT: Tôi chỉ tình cờ đọc được hai bài báo này, điều này giải thích nó tốt hơn tôi:

• Lời xin lỗi trong mã
• Cần bình luận

Tôi nghĩ quy tắc này khá đơn giản: hãy tưởng tượng một người hoàn toàn xa lạ nhìn thấy mã của bạn. Bạn có thể sẽ là một người xa lạ với mã của riêng bạn trong 5 năm. Cố gắng giảm thiểu nỗ lực tinh thần để hiểu mã của bạn cho người lạ này.

Một ý tưởng tốt để có những bình luận đúng là bắt đầu bằng việc viết bình luận.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Điều này cho phép bạn trích xuất các phương thức dễ dàng để thậm chí loại bỏ các bình luận,
chỉ cần để mã cho những điều này ! Xem cách viết lại (cắt / dán) theo cách rất hay:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Đối với những thứ không thể tách rời, chỉ cần trích xuất các phương thức và nhập mã dưới các bình luận.

Đây là những gì tôi thấy là một cách hữu ích để tiếp tục bình luận ở mức tối thiểu, thật sự vô ích khi bình luận từng dòng ... Chỉ ghi lại một dòng duy nhất nếu đó là về khởi tạo giá trị ma thuật hoặc ý nghĩa của nó.

Nếu các tham số được sử dụng quá nhiều, thì chúng phải là thành viên riêng trong lớp của bạn.

Tôi nghĩ rằng câu trả lời là thông thường "Nó phụ thuộc". Mã nhận xét chỉ để nhận xét mã là một mùi. Mã nhận xét bởi vì bạn đang sử dụng thuật toán tối nghĩa, thứ tự cường độ nhanh hơn sẽ tiết kiệm cho lập trình viên bảo trì (thường là tôi 6 tháng sau khi tôi viết nó) nửa ngày chọc qua mã để xác định xem nó đang làm gì.

// Dear me in the future. Please, resolve this problem.

hoặc là

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

Nhận xét mã chắc chắn không phải là "mùi mã". Niềm tin này thường xuất phát từ thực tế là các bình luận có thể trở nên cũ kỹ (lỗi thời) và có thể khó duy trì. Tuy nhiên, có những bình luận tốt giải thích tại sao mã đang làm một cái gì đó theo một cách nhất định có thể (và thường là) quan trọng để bảo trì.

Nhận xét tốt giúp dễ hiểu mã hơn đang làm gì và quan trọng hơn, tại sao nó lại thực hiện theo cách cụ thể. Nhận xét có nghĩa là được đọc bởi các lập trình viên và nên rõ ràng và chính xác. Một bình luận khó hiểu hoặc không chính xác không tốt hơn nhiều so với việc không có bình luận nào cả.

Việc thêm các nhận xét rõ ràng và chính xác vào mã của bạn có nghĩa là bạn không cần phải dựa vào bộ nhớ để hiểu về những gì mà Cameron và các lý do tại sao của một phần của mã. Điều này là quan trọng nhất khi bạn xem mã đó sau này hoặc người khác phải xem mã của bạn. Vì các bình luận trở thành một phần của nội dung văn bản trong mã của bạn, nên chúng phải tuân theo các nguyên tắc viết tốt ngoài việc được viết rõ ràng.

Để viết một bình luận tốt, bạn nên cố gắng hết sức để ghi lại mục đích của mã (tại sao, không phải như thế nào) và chỉ ra lý do và logic đằng sau mã càng rõ ràng càng tốt. Tốt nhất, bình luận nên được viết cùng lúc với bạn viết mã. Nếu bạn chờ đợi, có lẽ bạn sẽ không quay lại và thêm chúng.

Sams tự dạy mình bằng hình ảnh C # 2010 trong 24 giờ , trang 348-349.

Nếu mã đã được viết theo một cách cụ thể để tránh sự cố xảy ra trong thư viện (cả thư viện của bên thứ ba hoặc thư viện đi kèm với trình biên dịch), thì sẽ có ý nghĩa để nhận xét nó.
Nó cũng có ý nghĩa để nhận xét mã cần được thay đổi trong các phiên bản trong tương lai hoặc khi sử dụng phiên bản mới của thư viện hoặc khi chuyển từ PHP4 sang PHP5, chẳng hạn.

Ngay cả cuốn sách được viết tốt nhất vẫn có khả năng có phần giới thiệu và tiêu đề chương. Nhận xét trong mã tài liệu tốt vẫn hữu ích để mô tả các khái niệm cấp cao và giải thích cách tổ chức mã.

Đề cập đến danh dự là chống mẫu:

Tôi ấn tượng rằng đôi khi các phần mở đầu giấy phép FLOSS thường được sử dụng thay cho tài liệu tệp. GPL / BSDL tạo ra một văn bản phụ đẹp và sau đó bạn hiếm khi thấy bất kỳ khối nhận xét nào khác.

Tôi không đồng ý với ý kiến ​​rằng viết bình luận để giải thích mã là xấu. Điều này hoàn toàn bỏ qua thực tế là mã có lỗi. Có thể rõ ràng những gì mã làm mà không có ý kiến. Nó ít có khả năng rõ ràng những gì mã phải làm. Không có ý kiến, làm thế nào để bạn biết nếu kết quả sai, hoặc chúng được sử dụng không chính xác?

Các ý kiến ​​nên giải thích mục đích của mã, để nếu có lỗi, ai đó đọc các bình luận + mã có cơ hội tìm thấy nó.

Tôi thường thấy mình viết bình luận nội tuyến trước khi tôi viết mã. Bằng cách này, rõ ràng tôi đang cố gắng viết mã để làm gì và giảm bị lạc trong thuật toán mà không thực sự biết bạn đang cố gắng làm gì.

Nhận xét được đưa vào vì ai đó nghĩ rằng có thể có 700 dòng trong một phương thức là một mùi.

Nhận xét là có bởi vì bạn biết nếu bạn không đưa ra nhận xét, ai đó sẽ mắc lỗi tương tự một lần nữa là một mùi.

Nhận xét đưa vào bởi vì một số công cụ phân tích mã yêu cầu nó cũng là một mùi.

Những người sẽ không bao giờ đưa ra một nhận xét, hoặc viết thậm chí một chút giúp đỡ cho các nhà phát triển khác cũng là một mùi. Tôi ngạc nhiên khi có nhiều người sẽ không viết ra những thứ đó, nhưng sau đó sẽ quay lại và thừa nhận họ không thể nhớ những gì họ đã làm 3 tháng trước. Tôi không thích viết tài liệu, nhưng tôi muốn nói với mọi người điều tương tự lặp đi lặp lại thậm chí ít hơn.

Tôi sẽ trả lời với một câu hỏi của riêng tôi. Bạn có thể tìm thấy lỗi trong mã chưa hoàn thành dưới đây?

tl; dr: Người tiếp theo duy trì mã của bạn có thể không giống như bạn.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

Bạn phải giữ cân bằng giữa mã và bình luận ... Thông thường tôi cố gắng thêm một số bình luận tiếp tục một khối mã. Không phải vì tôi sẽ không thể hiểu được mã (cũng vậy), mà bởi vì tôi có thể đọc mã của chính mình nhanh hơn và xác định các phần cụ thể nơi xảy ra nội dung quan trọng.

Dù sao, tiêu chí cá nhân của riêng tôi là "khi nghi ngờ, bình luận". Tôi thích có một dòng dự phòng hơn là một dòng hoàn toàn khó hiểu mà tôi sẽ không thể hiểu được. Tôi luôn có thể xóa nhận xét về đánh giá mã, sau một thời gian (và tôi thường làm)

Ngoài ra, các bình luận khá hữu ích khi thêm "hãy cẩn thận" như "Hãy cẩn thận! Nếu định dạng của đầu vào không phải là ASCII, mã này sẽ phải thay đổi!"

Đọc điều này tôi được nhắc nhở về một cái gì đó mà lần đầu tiên tôi đọc (từ một danh sách dài hơn, được bảo quản bằng cách chụp bản sao) vài thập kỷ trước:

Các lập trình viên thực sự không viết bình luận - nếu khó viết thì khó đọc

Một mùi methinks khá cũ.

Tôi nghĩ rằng nhận xét mã được một khởi đầu rất nghèo cho cuộc sống. Tôi không biết về những ngày này, nhưng khi tôi lần đầu tiên được dạy lập trình ở trường, tôi đã nhận được các bài tập về bản chất của "Viết chương trình in các số từ một đến mười trên các dòng riêng biệt. Hãy chắc chắn rằng bạn nhận xét mã của mình." Bạn sẽ bị đánh dấu xuống nếu bạn không thêm nhận xét vì nhận xét mã của bạn là một điều TỐT.

Nhưng có gì để nói về một quá trình tầm thường như vậy? Vì vậy, cuối cùng bạn viết cổ điển

i++; // add one to the "i" counter.

chỉ để có được một điểm tốt và, nếu bạn có bất kỳ nous nào, ngay lập tức hình thành một ý kiến ​​rất thấp về nhận xét mã.

Mã nhận xét không phải là một điều tốt. Đó là một điều cần thiết, và Thomas Owens trong câu trả lời hàng đầu cung cấp một lời giải thích tuyệt vời về các tình huống cần thiết. Tuy nhiên, những tình huống này hiếm khi tăng lên trong các bài tập loại bài tập về nhà.

Theo nhiều cách, việc thêm một bình luận nên được coi là lựa chọn cuối cùng, khi những gì cần nói không thể được nói rõ ràng trong các phần hoạt động của ngôn ngữ lập trình. Mặc dù việc đặt tên đối tượng có thể trở nên cũ kỹ, các cơ chế thiếu phản hồi của con người và máy tính giúp bạn dễ dàng quên việc duy trì các bình luận và do đó các bình luận trở nên cũ kỹ nhanh hơn nhiều so với mã hoạt động. Vì lý do đó, khi có thể lựa chọn, việc thay đổi mã để làm cho nó rõ ràng hơn nên luôn luôn được ưu tiên để chú thích mã không rõ ràng bằng các bình luận.

Tất nhiên ý kiến ​​là một mùi mã ...

mọi lập trình viên đều biết tất cả chúng ta cuối cùng trở nên điên loạn do khối lượng công việc, gỡ lỗi hoặc chỉ là sự điên rồ đơn giản mà chúng ta gặp phải.

"Làm cái này!" quản lý dự án của bạn nói.

Bạn trả lời, "Không thể làm được."

Họ nói: "Sau đó, chúng tôi sẽ tìm người khác để làm điều đó."

Bạn nói, "OK, có lẽ nó có thể được thực hiện."

Và sau đó dành số X ngày tiếp theo .. tuần .. tháng .. cố gắng tìm ra nó. Trong suốt quá trình, bạn sẽ thử và thất bại, và thử và thất bại. Tất cả chúng ta làm điều này. Câu trả lời đúng là có hai loại lập trình viên, những người bình luận và những người không bình luận.

1) Những người đang làm cho công việc của họ trở nên dễ dàng hơn bằng cách ghi lại tài liệu tham khảo trong tương lai, nhận xét các thói quen thất bại không hoạt động (mùi không xóa chúng sau khi tìm thấy công việc đó.) định dạng để hy vọng làm cho nó dễ đọc hoặc dễ hiểu hơn một chút. Nghiêm túc mà nói, tôi không thể đổ lỗi cho họ. Nhưng cuối cùng, họ chụp và sau đó bạn có điều này: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Những người không giả vờ là siêu anh hùng hoặc đang sống trong hang động . Họ chỉ đơn giản là coi thường người khác, bản thân họ, và có thể quan tâm ít hơn về mã, hoặc ý nghĩa của nó có thể có cho sau này.

Bây giờ đừng hiểu sai về tôi .. các biến và chức năng tự ghi lại tài liệu có thể tránh điều này hoàn toàn .. và tin tôi đi, bạn không bao giờ có thể thực hiện đủ việc dọn mã. Nhưng sự thật đơn giản là miễn là bạn giữ bản sao lưu, bạn có thể luôn luôn xóa bình luận.

Tôi cho rằng việc không sử dụng một số bình luận trong mã của bạn là mùi mã. Mặc dù tôi đồng ý rằng mã phải tự ghi lại càng nhiều càng tốt, bạn nhấn vào một điểm nhất định nơi bạn sẽ thấy mã không có ý nghĩa bất kể mã được viết tốt như thế nào. Tôi đã thấy một số mã trong các ứng dụng kinh doanh trong đó các ý kiến ​​bắt buộc khá nhiều vì:

1. Bạn cần phải làm một cái gì đó trong từng trường hợp và không có logic tốt cho nó.
2. Mã có thể sẽ thay đổi trong một hoặc hai năm khi luật được thay đổi và bạn muốn tìm lại nó một cách nhanh chóng.
3. Ai đó đã chỉnh sửa mã trong quá khứ vì họ không hiểu mã đang làm gì.

Ngoài ra, hướng dẫn kiểu công ty có thể yêu cầu bạn làm điều gì đó theo một cách nhất định - nếu họ nói rằng bạn có thể có ý kiến ​​nêu rõ các khối mã trong một chức năng đang làm gì, sau đó bao gồm các nhận xét.

Có một sự khác biệt cơ bản lớn giữa các bình luận và mã: các bình luận là một cách để mọi người truyền đạt ý tưởng cho người khác, trong khi mã chủ yếu dành cho máy tính. Có nhiều khía cạnh trong "mã" cũng chỉ dành cho con người, như đặt tên và thụt lề. Nhưng ý kiến ​​được viết nghiêm ngặt cho con người, bởi con người.

Do đó, viết bình luận là một chút khó khăn như bất kỳ giao tiếp bằng văn bản của con người! Người viết nên có một quan niệm rõ ràng về đối tượng là ai, và họ sẽ cần loại văn bản nào. Làm thế nào bạn có thể biết ai sẽ đọc ý kiến ​​của bạn trong mười, hai mươi năm nữa? Điều gì xảy ra nếu người đó đến từ một nền văn hóa hoàn toàn khác? V.v. Tôi hy vọng mọi người hiểu điều này.

Ngay cả trong nền văn hóa đồng nhất nhỏ bé mà tôi sống, thật khó để truyền đạt ý tưởng cho người khác. Giao tiếp của con người thường thất bại, ngoại trừ do tai nạn.

Tôi phải đồng ý với đồng nghiệp của bạn. Tôi luôn nói rằng nếu tôi nhận xét mã của mình, điều đó có nghĩa là tôi lo lắng rằng tôi sẽ không thể tìm ra mã của riêng mình trong tương lai. Đây là một dấu hiệu xấu.

Lý do duy nhất khác mà tôi rắc ý kiến ​​vào mã là để gọi ra một cái gì đó dường như không có ý nghĩa.

Những bình luận đó thường có dạng như:

//xxx what the heck is this doing??

hoặc là

// removed in version 2.0, but back for 2.1, now I'm taking out again

Nhận xét mã, khi áp dụng, các đơn vị của đối số và trả về hàm, trường cấu trúc, thậm chí các biến cục bộ có thể rất tiện dụng. Hãy nhớ tàu quỹ đạo sao Hỏa!

Đây là quy tắc của tôi:

• Viết mã và lưu trữ một bản tóm tắt ngắn của mã trong một tài liệu riêng biệt.
• Để lại mã một mình trong vài ngày để làm việc khác.
• Quay trở lại mã. Nếu bạn không thể hiểu ngay những gì cần làm, hãy thêm tóm tắt vào tệp nguồn.

Giáo dục đồng nghiệp của bạn về kỹ thuật lập trình biết chữ .

Không, bình luận không phải là mùi mã, chúng chỉ là một công cụ có thể bị lạm dụng.

Ví dụ về những bình luận tốt :

// Tôi nghĩ rằng đây là bằng cm. Cần điều tra thêm!

// Đây là một cách làm X thông minh

// Danh sách được đảm bảo không trống ở đây