it-swarm-vi.com

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

Một đồng nghiệp của tôi tin rằng bất kỳ sử dụng nhận xét trong mã (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?

100
Fishtoaster

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 trong mã cho những người khác nhìn vào 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ề 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.

167
Thomas Owens

Đ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 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 ta có thể hầu như không theo dõi nó.

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

110
Paul Nathan

Nhận xét nên giải thích tại sao chứ không phải như thế nào.

How loại bình luận thường được xử lý tốt hơn bằng cách 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)
75
Sam Saffron

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, v.v. tại sao một cái gì đó là cách nó có thể vô cùng có giá trị đối với kẻ ngốc đáng thương, người phải duy trì mã trong sáu tháng - đặc biệt là khi tên ngốc đáng thương đó kết bạn với 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.

32
BlairHippo

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.

29
Wizard79

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ì.

26
Bill

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ậ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à ý nghĩa của việc các bình luận có mùi mã.

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:

23
Rasmus Faber

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
23
user281377

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.

21
LennyProgrammers

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í thoát khỏi các bình luận,
[.__.] chỉ cần để mã nói 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ực 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.

11
Tamara Wijsman

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 người lập trình bảo trì (thường là tôi 6 tháng sau khi tôi viết nó) nửa ngày chọc vào mã để xác định xem nó đang làm gì.

10
Brandon
// 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.
10
Zzz

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 nhận xét khó hiểu hoặc không chính xác là 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 được 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 đã giành chiến thắng trở lại và thêm chúng.

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

8
Scott Dorman

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ó.
[.__.] Cũng có ý nghĩa khi 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.

6
kiamlaluno

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ã.

6
munificent

Đề 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 của 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 điền vào Nice và sau đó bạn hiếm khi thấy bất kỳ khối nhận xét nào khác.

4
mario

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 mã làm gì mà không có nhận xét. Sẽ ít có khả năng rõ ràng mã được cho là để làm gì. 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 ý định của mã, để nếu có lỗi, ai đó đang đọ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 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ì.

4
Danny Tuppeny

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
3
Ant

Nhận xét được đưa vào vì ai đó nghĩ rằng có 700 dòng trong một phương pháp 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 nhận xét hoặc viết thậm chí một chút trợ 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 rồi 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.

3
MIA

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!"

2
Khelben

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.

2
Alohci

Đọ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ũ.

2
Murph

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 số 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 đều làm điều này. Câu trả lời thực sự 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.

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 hiệu quả.), Hoặc phá vỡ mã bằng nhận xét định dạng thành 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ó cái 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 hoàn toàn điều này .. và hãy tin tôi bạn không bao giờ có thể làm đủ mã dọn dẹp. 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.

1
Talvi Watia

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.

1
user15127

Tôi cho rằng việc không sử dụng một số nhận xét trong mã của bạn là mùi mã. Mặc dù tôi đồng ý rằng mã nên 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 hàm đang làm gì, thì hãy bao gồm các nhận xét.

1
rjzii

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 I sẽ không thể hiểu được của riêng tôi mã 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
0
Ken

Đây là quy tắc ngón tay cái 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ể ngay lập tức hiểu những gì nó phải làm, hãy thêm tóm tắt vào tệp nguồn.
0
Maxpm

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

0
SK-logic

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!

0
dmuir

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ề tốt ý kiến:

// 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

0
Andres F.

Tuy nhiên, mã không thể hiểu được chút nào lớn hơn mã mùi

Xin vui lòng cho tôi mã sạch để làm việc, tuy nhiên
[.__.] nếu đó không phải là một lựa chọn, tôi muốn có mã bẩn bẩn của Wikipedia với các bình luận
[.__.] hơn mã bẩn mà không có ý kiến.

0
Ian

Hầu hết các từ đã được đưa ra khỏi miệng của tôi. Nhưng tôi cho rằng tổng hợp tất cả: quan điểm của các bình luận là đưa ra một mô tả/giải thích cấp cao về những gì mã đang làm.

Hơn nữa, đây là một vài ví dụ về cách tôi sử dụng các bình luận:

  • như tiêu đề, để chỉ ra mục đích chung của một phần của mã
  • lưu ý nơi tôi có mã thông báo từ đó và do đó tránh đạo văn
  • thỉnh thoảng ở cuối các khối, để nhắc nhở khối nào là cuối của
  • để chỉ ra rằng mã có thể trông đáng ngờ là những gì được dự định (ví dụ: những thời điểm kỳ quặc khi xảy ra trường hợp chuyển đổi)
  • để giải thích các toán học đằng sau một thuật toán
0
Stewart

Không ai nói điều này cho đến nay trong chủ đề này, vì vậy tôi sẽ:

Nhập tên, tên biến, tên hàm, tên phương thức và nhận xét chỉ là siêu dữ liệu về mã của bạn và không liên quan gì đến mã máy mà trình biên dịch tạo ra (tất nhiên trừ tên của các ký hiệu được xuất và gỡ lỗi).

Tên loại và tên biến là danh từ, tên hàm và phương thức là động từ của bạn, với những bước bạn mô tả các bước sẽ được thực hiện. Bình luận là cho tất cả mọi thứ khác.

Vài ví dụ:

double temperature; // In Kelvins.


/**
 * Returns true if ray hits the triangle
 */
bool castRayOnTriangle(Triangle t, Ray r)
{
    //...
    if (determinant == 0)
    {
        /* The ray and the triangle are parallel, no intersection possible.*/
        return false;
    }
    //...
}


/* X algorithm. Visit http://en.wikipedia.org/... for details.*/
<implementation of something difficult to understand for the layman algorithm. >

Nhận xét có thể bacome lỗi thời, nếu không được cập nhật, nhưng tên biến và hàm cũng có thể trở nên lỗi thời. Gần đây tôi đã gặp trường bufPtr trong cấu trúc C, không liên quan gì đến bộ đệm hoặc con trỏ. Và tôi đã thấy một hàm inflateBuffer không giải nén dữ liệu bị xì hơi nhưng là tệp GZIP hoàn chỉnh ... Đây là những điều gây phiền nhiễu như những bình luận lỗi thời.

0
Calmarius

Có vẻ như không có quá nhiều câu trả lời xem xét lập trình theo nhóm. Tôi là một nhà phát triển cao cấp và tôi có xu hướng viết bình luận nhằm giải thích những gì đơn giản để tôi hiểu.

Tôi thấy nó là một hình thức của truyền thông hoặc giáo dục đội ngũ truy tặng. Tôi khuyến khích nhóm xem qua mã họ đang sử dụng, nhưng có lẽ chưa viết để hiểu rõ hơn về mã.

Một vài ví dụ từ tuần này (mã PHP):

//Pattern for finding jpeg photos
//Case insensitive pattern for jpg and jpeg
const PATTERN_PHOTO = "*.{[jJ][pP][gG],[jJ][pP][eE][gG]}";

Tôi hy vọng cái tên PATTERN_PHOTO sẽ hữu ích sau này trong mã để giải thích những gì nó làm, nhưng không có ý kiến ​​thì nó sẽ rõ ràng như thế nào đối với một nhà phát triển cơ sở, mẫu cụ thể này làm gì?

Cùng một bộ mã:

//Ignore . and .. directories in Linux
if($file != "." && $file != "..")

Có một kỳ vọng rằng các nhà phát triển của chúng tôi biết PHP, nhưng họ không hiểu HĐH Linux mà chúng tôi đang sử dụng để lưu trữ.

Vì vậy, tôi thấy những nhận xét này thực sự làm tăng hiệu quả chung của nhóm chúng tôi trong thời gian rất ít để viết chúng.

  • Có ít trường hợp người viết lại mã đơn giản chỉ vì họ không hiểu cách thức hoạt động của nó. "Tôi không hiểu nó đã làm như thế nào, nên tôi đã sửa nó." Nghiêm túc mà nói, tôi đã phải đối phó với điều này trước đây.
  • Có ít câu hỏi hơn về các đoạn mã riêng lẻ. Trả lời các câu hỏi chỉ một lần, thường yêu cầu tra mã và thời gian để tôi làm quen lại với nó. Và đôi khi tôi sẽ nhận được cùng một câu hỏi từ hơn một người cách nhau vài tuần. (Vâng, nó sẽ là những thứ đơn giản như các ví dụ ở trên)
  • Các nhà phát triển khác được khuyến khích và hướng dẫn để tự học. Tôi hy vọng rằng nếu họ đi qua //Ignore . and .. directories in Linux họ có thể sẽ nhảy vào Google và đột nhiên hiểu Linux hơn một chút.
0
Chris