Tôi đã có một tìm kiếm nhưng không tìm thấy những gì tôi đang tìm kiếm, xin vui lòng liên kết với tôi nếu câu hỏi này đã được hỏi.

Đầu tháng này, bài viết này đã được thực hiện:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

Về cơ bản để tóm tắt, bạn là một lập trình viên tồi nếu bạn không viết bình luận. Ý kiến ​​cá nhân của tôi là mã phải được mô tả và chủ yếu không yêu cầu bình luận trừ khi mã không thể tự mô tả.

Trong ví dụ đã cho

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Tác giả cho biết mã này nên được đưa ra một nhận xét, ý kiến ​​cá nhân của tôi là mã nên là một lệnh gọi mô tả:

$extension = GetFileExtension($image_filename);

Tuy nhiên, trong các ý kiến ​​ai đó thực sự đưa ra gợi ý đó:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

Tác giả đã trả lời bằng cách nói rằng người bình luận là "một trong những người đó", tức là một lập trình viên tồi.

Mọi người đều có quan điểm gì về Mã tự mô tả so với Mã nhận xét?

Tôi thích viết mã tài liệu tự. Hướng dẫn cho việc này là Clean Code .

Tất nhiên điều này không có nghĩa là người ta không bao giờ nên sử dụng bình luận - họ có vai trò của họ, nhưng IMHO bạn nên sử dụng chúng một cách cẩn thận. Câu trả lời trước đó của tôi về SO giải thích suy nghĩ của tôi về chủ đề này chi tiết hơn.

Tất nhiên, như @Niphra lưu ý, luôn đáng để kiểm tra lại rằng những gì tôi tin là sạch sẽ thực sự dễ hiểu bởi những người khác. Tuy nhiên, đây là một câu hỏi thực hành quá. Quay trở lại uni tôi đã viết các đoạn mã khó hiểu chỉ đơn giản là do sử dụng các tên lạ và hài hước cho tất cả các thực thể mã, theo ý thích của tôi. Cho đến khi giáo viên của tôi rút lại một trong những bài tập của tôi, lưu ý một cách lịch sự rằng anh ta không thể tìm ra mô-đun nào là chính :-) Đó là một bài học tốt, vì vậy tôi đã cố gắng tập trung vào việc viết mã dễ đọc hơn kể từ đó. Ngày nay tôi hầu như không nhận được lời phàn nàn từ đồng đội.

Bạn không nên ghi lại những gì mã đang làm, nhưng bạn nên ghi lại lý do tại sao nó làm điều đó.

Không có số lượng các thủ thuật đặt tên sẽ làm lộ ra các whys và wherefores, vì vậy bạn phải thêm ý kiến ​​để giải thích mục đích của các bit mã khác nhau.

Tất cả các ý kiến ​​khác có thể được thoát khỏi một cách an toàn.

Tôi thực sự không tin vào mã tự mô tả. Có nhiều mã dễ đọc hơn và mã dễ đọc hơn , tùy thuộc vào ngôn ngữ, kiến ​​thức của bạn về nó (với tư cách là tác giả gốc), kiến ​​thức của anh chàng đọc nó và chức năng mã. Nhưng không, vẫn ... nó nên được mô tả với một bình luận ngắn.

Điều rõ ràng với tôi bây giờ, rằng tôi đang ở trong khu vực suy nghĩ đó có thể sẽ không rõ ràng với tôi trong một năm, khi tôi nghĩ về điều gì đó hoàn toàn khác biệt và cần sử dụng lại phần mã này.

Vì vậy, nhận xét mã của bạn. Tất nhiên không phải tất cả các dòng (trời tốt, không), nhưng đặt một vài dòng nhận xét bên trên một hàm / chương trình con / mô-đun , hoặc một phần đặc biệt khó khăn và nói ngắn gọn về những gì nó làm. Bạn sẽ cảm ơn chính mình trong một hoặc hai năm.

May mắn thay, cả hai phe trong cuộc thảo luận này được trình bày ở đây, và các đối số pro và con cho cả hai đã được đề cập.

Tôi tin rằng cả hai phe có những tranh luận chồng chéo, và thực sự đồng ý với hầu hết trong số họ, chỉ là cách làm thế nào để đạt được chúng là một chút khác nhau.

Đối số chồng chéo

• Mã nên được đọc.
• Nhận xét không nên nói chính xác điều tương tự như mã, nhưng cung cấp cái nhìn sâu sắc hơn khi cần thiết.
• Tất cả các tên biến / hàm nên được suy nghĩ tốt để chúng thể hiện tốt những gì chúng đang / làm.
• Mã trùng lặp nên được ngăn chặn.

Bây giờ, sự khác biệt chính là trọng lượng được đặt vào một số trong những đối số đó.

Mã tự mô tả

• Nhận xét có thể bị lỗi thời, vì vậy giảm thiểu sử dụng chúng, vì nhận xét sai còn tệ hơn không có nhận xét.
• Nhận xét là một bản sao của mã. Tất cả mọi thứ có thể được viết bằng mã, nên được viết bằng mã.

Thêm ý kiến

• Nhận xét dễ đọc hơn mã. Tiếng Anh đơn giản là tốt hơn để mô tả một cái gì đó.

• Mã đơn giản thường gây ra sự mơ hồ mà phải được bình luận bằng mọi cách. Cố gắng mô tả điều này trong mã, kết quả là tên quá dài. Hơn nữa, bạn liên tục phải đối mặt với thông tin 'thêm' này mà bạn chỉ cần lần đầu tiên bạn bắt gặp nó.

Tôi tin rằng cả hai trại đều có lý lẽ rất hợp lệ, nhưng bạn không nên điên cuồng theo dõi một trại, chỉ vì nó giải quyết được một vấn đề.

Để chứng minh, trong cuốn sách Clean Code , mã được chia thành nhiều phương thức nhỏ hơn chỉ được gọi một lần. Các phương thức được tạo ra vì lý do duy nhất để ghi lại mã (và TDD dễ dàng hơn). Điều này dẫn đến chức năng Hell . Mã này ít đọc hơn ban đầu và trong khi tái cấu trúc, không có ý nghĩ nào được đưa ra để đóng gói mã có thể tái sử dụng.

Mặt khác, bạn thường thấy API nơi mọi chức năng được nhận xét, chỉ vì 'nhận xét là tốt'. Những điều đáng lẽ phải được bình luận vẫn không có.

"Tôi xin lỗi nhưng anh chàng đó."

Tôi tự hỏi tại sao anh ấy không thích bình luận: P

Nghiêm túc mà nói, mã hóa là quá nhiều nghệ thuật mà người ta có thể thực sự đưa ra một tuyên bố sâu rộng như vậy. Đôi khi bạn cần bình luận, đôi khi nhiều chức năng được đặt tên tốt hơn. Thường là cả hai.

Tra cứu lập trình biết chữ như một phong cách cực đoan.

Câu trả lời ngắn gọn, tốt hơn và đúng

Ý tưởng rằng "mã tự viết" được viết tốt là tất cả những gì bạn cần là một mô hình chống và sẽ chết, ngay cả khi nó đưa ra ngoại lệ cho các bình luận giải thích "tại sao". Thật hoang đường khi bạn luôn có thể viết tất cả mã cho bất kỳ thuật toán nào đủ rõ ràng để bất kỳ lập trình viên nào lướt qua và lấy nó (hoặc nó sẽ không yêu cầu tái cấu trúc hoặc thời gian tổ chức mà bạn không có). Thậm chí quan trọng hơn, thường xuyên hơn không, các lập trình viên nghĩ rằng họ viết mã rõ ràng thì không.

Một câu trả lời tốt hơn nhiều so với các bình luận chỉ nên được sử dụng để giải thích "tại sao" là các bình luận nên:

• giải thích "tại sao" (tất nhiên)
• chỉ giải thích "cái gì" trên các dòng riêng lẻ khi mã phức tạp hoặc mục đích không rõ ràng và nó không thể hoặc không đáng để đơn giản hóa hơn nữa
• giải thích "cái gì" cho các khối mã để tăng tốc độ hiểu và định vị những gì bạn cần

Giải thích để sao lưu

Mọi người lầm tưởng lý do duy nhất mọi người sử dụng các bình luận là để giải thích ý nghĩa của một dòng mã. Sự thật là một mục đích lớn của mã nhận xét là làm cho nó nhanh hơnđể lướt qua mã của bạn và tìm thấy những gì bạn đang tìm kiếm. Khi tôi quay lại mã sau hoặc đọc mã của người khác, chắc chắn, tôi có thể đọc và hiểu một phần của mã được viết tốt - nhưng không phải là nhanh hơn và dễ dàng hơn để đọc nhận xét ở đầu nói rằng phần mã đó làm gì và bỏ qua nó hoàn toàn nếu nó không phải là những gì tôi đang tìm kiếm? Tại sao lại ngồi đó và tìm ra mã, ngay cả khi nó được viết tốt, nếu bạn có thể lướt qua một vài bình luận và hiểu toàn bộ chức năng? Đó là lý do tại sao chúng tôi sử dụng tên mô tả cho các hàm - không ai nói rằng tôi không cần sử dụng tên mô tả cho chức năng của mình vì ai đó chỉ cần xem qua mã được viết sạch của tôi để xem nó làm gì.

Ví dụ: nếu tôi đang xem qua chức năng của người khác, việc đi từng dòng qua mã sẽ dễ dàng hơn để xem những gì nó đang làm hoặc lướt qua ba nhận xét được viết tốt trong suốt chức năng để xem chính xác chức năng đang làm gì và ở đâu nó đang làm à?

Một mô hình chống khác là việc lạm dụng các hàm để nhận xét mã của bạn. Các hàm được đặt tên tốt là một phần quan trọng của tài liệu mã, nhưng đôi khi các lập trình viên tách 2-3 dòng mã sẽ không bao giờ được sử dụng ở bất kỳ nơi nào khác thành hàm cho mục đích tài liệu. Tại sao lạm dụng chức năng bất kỳ tốt hơn so với lạm dụng bình luận? Sử dụng các hàm như thế cũng giống như chấp nhận các câu lệnh GOTO - nó tạo ra mã spaghetti có thể là một nỗi đau để làm theo.

Về cơ bản, khi bạn làm việc trong môi trường doanh nghiệp, nơi mọi người liên tục chia sẻ mã và mọi người không có thời gian để làm cho mã của họ hoàn hảo, một vài bình luận tốt có thể tiết kiệm hàng tấn thời gian và sự thất vọng. Và hãy nhớ rằng, trong khi bạn có thể là một bậc thầy có thể đọc mã với tốc độ ánh sáng, thì không phải ai trong văn phòng của bạn cũng vậy.

Chà, bạn cũng phải nhớ một cái gì đó rõ ràng hoặc "tự ghi lại" cho bạn, có thể không phải là cho người khác ... Có thể ai đó ít hiểu biết về các chức năng nhất định. Vì vậy, tôi nhận xét về tất cả mọi thứ.

Chà, điều với mã tự ghi là trong hàm đó, bạn sẽ tìm thấy:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Điều này tự giải thích khi bạn có tên hàm vì nó chỉ có hai dòng. Khi mọi thứ trở nên phức tạp hơn, bạn phải bọc mỗi vài dòng mã trong một hàm bằng một tên mô tả hoặc sử dụng các nhận xét khi cần thiết .

Tôi không bao giờ hiểu tại sao nó nên là một hoặc / hoặc vật chất, thay vì và / và. Có, làm cho mã của bạn càng nhiều tài liệu càng tốt, và vâng, thêm một số nhận xét vào các phần mà nếu không thì không rõ ràng.

Nhận xét và mã sạch tự ghi là khác nhau. Mã là tất cả về cách làm việc. Và các bình luận nên bao gồm phần lý do tại sao không thể giải thích bằng mã, bất kể ngôn ngữ của bạn là gì. Ngoài ra, nếu ngôn ngữ của bạn rất hạn chế và bạn không có hợp đồng, không có thông số kỹ thuật tĩnh và thậm chí không có xác nhận, các bình luận sẽ đề cập đến các vấn đề ranh giới của mã của bạn.

Trong trường hợp đó, thật dễ dàng để tạo một chức năng mô tả. Nhưng tôi đã đọc rất nhiều mã được tạo bởi các lập trình viên giỏi, những người tin rằng mã của họ là tự viết tài liệu, và những gì rõ ràng đối với họ thực sự khó hiểu với tôi.

$ extension = GetFileExtension ($ image_name);

Để lấy lại ví dụ của bạn, tôi có thể gửi một mảng tên hình ảnh cho nó không, hay nó chỉ lấy một hình ảnh? Nó có hỗ trợ bất kỳ loại tập tin, hoặc chỉ một số trong số họ? Nó sẽ bảo mật chuỗi cho tôi, hay tôi phải làm điều đó? Nếu loại tệp không tồn tại, nó có thông báo cho tôi không?

Tất nhiên, tôi kéo dài cái này một chút. Nhưng tôi nhớ một lập trình viên tin rằng audio_bandband và video_bandband là tên tự ghi; hóa ra âm thanh phải được thể hiện bằng byte và video tính bằng kilobyte. Mất rất nhiều thời gian để tìm ra điều đó.

Một cái không loại trừ cái kia. Mặc dù mã của bạn là tự nhận xét, nhưng đôi khi bạn có thể cần bình luận thường xuyên để giải thích lý do tại sao mã tự nhận xét của bạn làm những gì nó làm.

Tôi không đồng ý với bài viết đó và đồng ý với bạn ở một mức độ nào đó. Nếu bạn sử dụng tên phương thức tốt, tên biến tốt và phương thức nhỏ làm một việc duy nhất, mã sẽ đơn giản để làm theo.

Chỉ cần cố gắng không khéo léo vì mã thông minh là đọc và duy trì khủng khiếp. Từ khóa: duy trì !

Ý kiến ​​của tôi là ý kiến ​​nên mô tả lý do tại sao và không phải là những gì. Hãy nhớ trong thế giới hoàn hảo giả thuyết này, mã của bạn đủ sạch để cho phép dễ đọc, bạn không cần phải giải thích những gì nó đang làm, nhưng tại sao bạn lại chọn làm theo cách này hay cách khác.

Nếu bạn đang sử dụng hệ thống kiểm soát nguồn, bạn có thể sử dụng thông điệp cam kết để cho mọi người (và chính bạn) biết bạn đã làm gì tại một thời điểm nhất định và quan trọng hơn là tại sao.

Bạn sẽ muốn tránh viết bình luận giống như bạn muốn tránh bất kỳ tài liệu nào. Khi nói đến ngôn ngữ lập trình, mọi người đều vận hành từ cùng một bộ từ vựng và cú pháp (gần như).

Khi ứng dụng của bạn dành cho một tên miền cụ thể, có thể khó để mọi người tham gia đồng ý và / hoặc thiết lập một từ vựng chung. Chúng tôi được dạy để tránh viết tắt và biệt ngữ mở rộng, nhưng tôi sẽ gọi nó là

EBITDA

và không

EquityB BeforeInterestTaxesDepreciationAndAmortization

Nếu bạn không biết cái này, có lẽ bạn không hiểu cái kia. Nếu công ty có một số triển khai không phổ biến, một nhận xét sẽ giúp lập trình viên tiếp theo có thể có kinh nghiệm trong lĩnh vực này, nhưng không phải là công ty đặc biệt này (Điều này chỉ khiến mọi việc phức tạp hơn.).

Tôi nghĩ rằng chúng ta cần phân biệt giữa tài liệu và tính biểu cảm của mã.

Khi gỡ lỗi hoặc xem lại mã, bạn không đọc sách. Hầu hết thời gian bạn chỉ muốn chuyển từ phương pháp này sang phương pháp khác và thực hiện các kết nối nhanh chóng trong tâm trí của bạn để có được sự hiểu biết cơ bản về những gì đang diễn ra trong thời gian chạy. Đó không phải là tài liệu xung quanh mã mà là tính biểu cảm của chữ ký mã quan trọng trong quy trình đó, khả năng của chúng đủ ý nghĩa để bạn có thể xác định ngay lập tức và thêm chúng vào ngăn xếp cuộc gọi nội bộ của riêng bạn. Tại thời điểm đó, bộ não của chúng ta (ít nhất là của tôi hoạt động theo cách đó;)) có xu hướng coi các khối nhận xét lớn như một tiếng ồn hơn là một sự trợ giúp. Do đó, các nhận xét một dòng, hoặc thậm chí tốt hơn, chỉ cần phương thức tự mô tả và tên đối tượng là đủ ở đây.

Nếu bạn muốn "đọc sách" của một lớp hoặc tính năng cụ thể, một nơi tốt hơn nhiều cho điều đó là trong các bài kiểm tra đơn vị. Các bài kiểm tra đơn vị được thiết kế tốt về bản chất là tiết lộ ý định và nhiều tài liệu hơn (nghĩa là giải thích, chi tiết) so với các khối nhận xét dày nhất vì chúng chứa 1 / kỳ vọng về chính xác những gì mã này phải làm và 2 / khả năng kiểm tra những kỳ vọng chống lại mã thực sự. Một bài kiểm tra vượt qua đáng tin cậy hơn hàng trăm lần so với bất kỳ nhận xét nào về tài liệu, bởi vì nó chứng minh rằng những gì nó khẳng định là đúng.

Một số mã không phải là tài liệu tự, và yêu cầu một số lời bình luận từ một người đồng bào đã hiểu và kiểm tra đoạn đó. Những gì tôi có dưới đây chỉ là không đủ để hiểu nó, tôi nghĩ.

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

Tôi thường thích viết mã tự viết tài liệu, với các bình luận không rõ ràng, vì tôi nghĩ rằng hầu hết các mã sẽ không hoàn toàn là tài liệu chính nó.

Tại trường đại học, chúng tôi được dạy cách viết lại khá nhiều dòng mã bằng tiếng Anh bằng một nhận xét (có lẽ chỉ để chúng ta có thói quen hiểu mã thực sự làm gì, thay vì chỉ sao chép / dán thứ gì đó và hy vọng điều tốt nhất).

Cá nhân, tôi cho rằng việc loại bỏ mã của bạn ra khỏi mã của bạn, làm cho nó ít đọc hơn nếu đó chỉ là nhận xét hoặc chỉ là mã. Tôi là một lập trình viên C # và những bình luận duy nhất tôi đưa ra mọi lúc là các khối nhận xét "ba dấu gạch chéo" được diễn giải trở lại tài liệu IntelliSense. Nếu tôi cảm thấy đặc biệt có lỗi về một cách cụ thể để làm một cái gì đó, orit trông đặc biệt khó hiểu, tôi sẽ giải thích thêm, nhưng đó là về nó.

IMO: Mã tự viết tài liệu là mã trong đó các tên biến và phương thức được đặt tên có ý nghĩa và theo ngữ cảnh, để chúng mô tả mục đích của chúng là gì.

Nếu bạn đã xem lại mã của mình nhiều lần mà vẫn không tìm được cách nào để làm rõ ý định cho một số người biết tên miền. Viết lại hàm. Sau tất cả, nó không quá 10-20 dòng. Nếu nó dài hơn thì hãy viết lại chức năng dù sao nó cũng dài và đó là một phần lý do tại sao nó không thể đọc được :) rửa lại

và trong trường hợp không thể xảy ra, vẫn chưa rõ mã đang làm gì và bạn đã nhớ yêu cầu đồng nghiệp giúp đỡ. Vậy thì tất cả chúng tôi cảm ơn bạn đã giúp phát triển Linux vì đó là mã hạt nhân bạn đang viết phải không? nếu không rửa lại từ đầu :)

Đơn giản chỉ cần không viết bình luận của bạn MÃ họ

Kiểm tra Code Complete phiên bản 2, pg 128-129.

Các loại dữ liệu trừu tượng sẽ cứu bạn khỏi câu hỏi hóc búa này. Mã tài liệu tự là cách để đi. Nhận xét có thể hữu ích, nhưng có

thực thể trong thế giới thực chứ không phải là triển khai cấp thấp

bạn có thể tránh sử dụng bình luận.

Một điều về ý kiến ​​là bạn viết chúng một lần, nhưng bạn không thấy chúng khi bạn thực hiện chức năng, bạn chỉ nhìn thấy chúng khi bạn thay đổi chức năng.

Nhận xét thực sự hữu ích khi được IDE diễn giải theo cách Delphi 2009+ hoặc JavaDoc hoạt động, nhưng đó là ngôn ngữ đánh dấu có cấu trúc, vì vậy theo nghĩa bạn đang lập trình tài liệu của mình, rất thông minh.

Tôi tin vào câu thần chú rằng mã không tự ghi lại, bởi vì bạn có thể là lập trình viên giỏi nhất thế giới (Ada), nhưng vẫn không hiểu điều gì đang xảy ra, nhưng nếu bạn viết tài liệu tại sao và trong một thời gian ngắn Làm thế nào mã của bạn đang làm những gì nó làm, bạn sẽ giúp chính mình và những người khác trong tương lai.

Bình luận là phải có. Bởi vì khi bạn viết mã, bạn đang viết cho nhu cầu hiện tại của mình, nhưng cũng cho những người trong tương lai phải đọc mã của bạn, tìm ra wtf, bạn đang làm gì, và tại sao, và sau đó làm thế nào để sửa đổi nó.

Nếu bạn chỉ ghi nhớ điều này, khi viết mã / lập trình?

Làm thế nào tôi có thể làm cho điều này dễ hiểu và sửa đổi hơn cho các lập trình viên tương lai của mã này mà tôi đang làm việc, sau đó bạn sẽ làm tốt công việc. Thất bại trong việc đó, bạn chỉ khiến người khác khó sửa đổi mã của mình và đừng tưởng tượng rằng sẽ không bao giờ xảy ra trường hợp đó, điều đó rất hiếm ...

Trong hầu hết các công việc của tôi, tôi luôn phải sửa đổi mã của người khác và được viết một cách khủng khiếp nhất, được ghi chép kém.

Vì vậy, thói quen của bạn để suy nghĩ tài liệu mã là tự nó, chỉ là không làm việc siêng năng.

Là lập trình viên, chúng ta phải thực hành kỷ luật tự giác dường như hoàn toàn đối với các lập trình viên thiếu kinh nghiệm, nhưng phải có thói quen, để tránh tất cả những trải nghiệm khủng khiếp mà chúng ta có với mã của người khác. Hoặc thậm chí nhìn vào mã của chúng ta nhiều tháng, nhiều năm sau.

Hãy xem http://thed Dailywtf.com họ có vô số câu chuyện hài hước nhưng có thật về những lập trình viên, những người không làm việc chăm chỉ của họ ..