Là những bình luận lỗi thời là một huyền thoại đô thị?

Tôi liên tục thấy mọi người đưa ra tuyên bố rằng "các bình luận có xu hướng trở nên lỗi thời". Vấn đề là, tôi nghĩ rằng tôi đã thấy có thể hai hoặc ba bình luận lỗi thời trong toàn bộ sự nghiệp của tôi. Thông tin lỗi thời trong các tài liệu riêng biệt xảy ra mọi lúc, nhưng theo kinh nghiệm của tôi, các bình luận lỗi thời trong chính mã là cực kỳ hiếm.

Tôi có may mắn khi làm việc với ai không? Là một số ngành công nghiệp nhất định có xu hướng vấn đề này hơn những ngành khác? Bạn có ví dụ cụ thể về những bình luận lỗi thời gần đây bạn đã thấy không? Hoặc là những bình luận lỗi thời nhiều hơn một vấn đề lý thuyết hơn là một vấn đề thực tế?

Liên tục

Tôi thực sự không thể tin rằng tôi là người duy nhất bơi trong những bình luận lỗi thời và sai lệch. Trong trường hợp tắt điều này sẽ giúp với sự hiểu biết:

Nó có lẽ phụ thuộc quan trọng nhất vào tuổi của mã. Yếu tố tiếp theo sẽ là doanh thu của nhân viên.

Tôi làm các phần bằng nhau R & D và công việc bảo trì. R & D là mã mới, thường là những thứ hơi lạc lối. Nhiều đồng nghiệp của tôi tin vào việc đưa ra nhiều lời giải thích được bình luận khi thử một cái gì đó không có thư viện ngoài kia. Vì tỷ lệ nhận xét trên mã cao hơn bình thường, nên có nhiều cơ hội hơn để mọi thứ không đồng bộ.

Mã bảo trì ... Tôi là một người bảo trì tích cực trên một hệ thống đã hơn 10 năm tuổi và một hệ thống khác trên 5. Mã và nhận xét 10 năm tuổi rất tồi tệ, như bạn mong đợi. Hơn 10 năm bạn có được rất nhiều tay trong codebase và không ai có ý tưởng gì về việc toàn bộ hoạt động như thế nào nữa. Mã và nhận xét 5 năm là khá tốt vì doanh thu trong nhóm đã khá thấp.

Tôi làm việc gần như tất cả các dịch vụ, thậm chí các sản phẩm của chúng tôi được tùy biến cao cho một khách hàng cụ thể.

Ví dụ cụ thể:

• Nhận xét mô tả sự cải thiện hiệu suất cho một phương pháp cụ thể, như tránh một bản sao trong bộ nhớ. Một vấn đề lớn khi một máy đầu cuối trong Pentium 2 có MB RAM, nhưng bây giờ hầu như không phải là vấn đề.

• TODO

• Các khối mã dán sao chép bao gồm cả ý kiến. Nhận xét có thể có ý nghĩa ở vị trí ban đầu của nó, nhưng hầu như không có ý nghĩa ở đây

• Các khối nhận xét trên đầu mã nhận xét (Ai biết được bao nhiêu năm ở đó).

Trong tất cả những điều này, bạn thấy một xu hướng chỉ không duy trì các bình luận và mã ở cùng cấp độ với phần mềm. IDE và thói quen phát triển cơ bản không giúp ích gì cho điều này, mắt tôi đã được đào tạo để vượt qua chúng. Tôi nghĩ rằng bình luận lỗi thời là tương đối rẻ để tránh trong các dự án hoạt động và lĩnh vực xanh. Nếu bạn có thể giữ tỷ lệ mã / bình luận cao, thì việc cập nhật chúng không phải là vấn đề lớn. Khó hơn một chút để biện minh cho việc săn lùng những thứ này khi bạn dự trù kinh phí x giờ để sửa lỗi trên hệ thống sản xuất.

"ý kiến ​​có xu hướng trở nên lỗi thời."

Tôi đã thấy điều này xảy ra thường xuyên đủ để biết đây có thể là một vấn đề.

Vấn đề là, tôi nghĩ rằng tôi đã thấy có thể hai hoặc ba bình luận lỗi thời trong toàn bộ sự nghiệp của tôi.

Tôi tin rằng hoàn toàn có thể làm việc trong một môi trường mà mọi người đều quan tâm đúng mức đến các bình luận và duy trì chúng. Chỉ cần một nỗ lực nhỏ để xem các bình luận gần mã bạn đang chỉnh sửa và cập nhật chúng khi thích hợp. Trong trường hợp các bình luận ở rất xa mà bạn không chú ý ngay lập tức, dù sao chúng cũng là những bình luận xấu và không nên thêm vào vị trí đầu tiên (hoặc ít nhất là không có ở đó).

Hơn nữa, thường cùng với tuyên bố rằng các bình luận có xu hướng trở nên lỗi thời, tuân theo tuyên bố rằng điều này làm giảm khả năng đọc và gây nhầm lẫn cho mọi người. Đây là điều mà tôi chưa có kinh nghiệm. Mỗi lần tôi gặp phải một bình luận lỗi thời, tôi thấy rõ những gì đã thay đổi và chỉ cập nhật nhận xét cho phù hợp để thể hiện mã mới hơn, mặc dù có thêm một số nỗ lực.

Một nghiên cứu gần đây của Roehm et al. Năm 2012 quan sát như sau:

21 người tham gia [trong số 28] đã báo cáo rằng họ có được thông tin chính từ mã nguồn và nhận xét nội tuyến trong khi chỉ có bốn người tuyên bố rằng tài liệu là nguồn thông tin chính của họ.

Điều này phù hợp với sự nghi ngờ của bạn rằng các bình luận trong chính mã nói chung vẫn được coi là rất hữu ích. Điều này chỉ ra rằng một dòng rõ ràng nên được rút ra giữa tài liệu lỗi thời và ý kiến ​​lỗi thời .

_{Roehm, T., Tiarks, R., Koschke, R., & Maalej, W. (2012, tháng 6). Làm thế nào để các nhà phát triển chuyên nghiệp hiểu phần mềm?. Trong Kỷ yếu của Hội nghị Quốc tế về Kỹ thuật phần mềm 2012 (trang 255-265). Báo chí của IEEE.}

Bình luận lỗi thời là một mùi công việc. Nó giống như đã kiểm tra đơn vị lỗi thời hoặc bị bỏ quên - nó cho thấy các quy trình tốt đã từng hoạt động tại cửa hàng đang thoái hóa thành mã hóa cao bồi. "Văn hóa kỹ thuật" thích hợp của việc dành thời gian để làm mọi thứ đúng cách đã bị phá vỡ. Dự án / công ty có khả năng đi vào nợ kỹ thuật.

Nói tóm lại, vâng, bạn đã may mắn. Nếu bạn tình cờ có một chuỗi các cửa hàng hoạt động hợp lý cho đến nay trong sự nghiệp của bạn, thì hoàn toàn không thể thấy điều này nhiều. Nhưng trong các cửa hàng điển hình hơn, ít hoạt động hơn, điều này chạy song song với phần còn lại của sự hỗn loạn.

Nhận xét giống như các bài kiểm tra, chúng rất tốt khi được cập nhật, nhưng có thể khiến việc hiểu mã trở nên khó khăn hơn nếu không có.

Nếu bạn chưa bao giờ thấy bất kỳ bình luận lỗi thời, bạn đã rất may mắn.

Hầu hết các cơ sở mã mà tôi đã làm việc với đầy những bình luận lỗi thời và thường thì tôi hoàn toàn không để ý đến các bình luận vì chúng thường là nguồn gây nhầm lẫn thay vì giúp đỡ.

Các bình luận lỗi thời thường xuất hiện trong JavaDoc:

• Liệt kê các đối số không còn tồn tại
• Không giải thích tất cả các đối số (những cái còn thiếu có lẽ đã được thêm vào sau)
• Những điều tương tự cho ngoại lệ, vv

Ngoài ra, đôi khi các bình luận nêu rõ những điều như "làm điều này ở đây để thực hiện" khi hầu hết các cân nhắc về hiệu suất có xu hướng trở nên cũ hơn nhanh hơn chính mã.

Thỉnh thoảng tôi đối phó với những bình luận lỗi thời. Nó chắc chắn không phải là một huyền thoại đô thị. Mọi người đề cập đến nó trong danh sách các thực hành tồi tệ nhất không phải vì nó đánh vào bạn rất thường xuyên mà bởi vì khi thực hiện, nó thường khiến bạn tốn rất nhiều thời gian và công sức.

Trong cơ sở mã của chúng tôi, hầu hết các bình luận lỗi thời là do sử dụng mẫu (chống) mô tả hành vi phương thức gần cuộc gọi của nó và không khai báo phương thức gần. Nó xảy ra khi ai đó trích xuất đoạn mã dài vào một phương thức chỉ được gọi một lần tại thời điểm đó và sau đó nhận xét cuộc gọi phương thức. Vì vậy, bạn kết thúc với một cái gì đó như thế này:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

Và phương pháp được khai báo ở đâu đó bên dưới mà không có ý kiến. Mọi người nhầm lẫn với các phương thức này trong nhiều năm đối phó với các thay đổi về thông số kỹ thuật và sửa lỗi, và cuối cùng bạn kết thúc với một phương pháp không sắp xếp danh sách và đưa ra một ngoại lệ khi tìm thấy tính năng trống. Vì vậy, nhận xét ở trên là một nhận xét lỗi thời mà cuối cùng sẽ khiến bạn mất một thời gian trong trình gỡ lỗi. Những điều này xảy ra trong một số cơ sở mã.

Hãy tự hỏi điều này. Bạn đã bao giờ thay đổi một dòng mã và không thay đổi các bình luận liên quan hoặc thêm những cái mới chưa?

Tôi đã làm việc với rất nhiều mã kế thừa và các bình luận đôi khi thậm chí không gần với liên quan.

Đối với hầu hết các phần, kinh nghiệm của tôi phù hợp với bạn nhưng tôi đã chạy qua một trường hợp điều đó đúng với tất cả các cơ sở mã. Đó là một ứng dụng đã được viết ra từ nhiều năm trước bởi một cửa hàng tư vấn không còn "về các điều khoản tốt" với khách hàng.

Công ty đã thực hiện một công việc đặc biệt để nhận xét mã, nhưng các lập trình viên đã duy trì nó kể từ khi bàn giao ban đầu là một phần của suy nghĩ "chỉ thay đổi những gì cần thay đổi hoàn toàn" mà bản thân nó không phải là xấu. Thật không may, họ cũng giữ thái độ tương tự đối với các bình luận, dẫn đến sự mất kết nối khá lớn giữa các bình luận và mã theo thời gian.

Tôi không thấy quá nhiều bình luận mô tả đã lỗi thời, nhưng tôi thấy rất nhiều bình luận TODO đã ở đó trong nhiều năm. Tôi ước họ giống như những viên nang thời gian và nói điều gì đó như thế này:

//TODO: In 15 years AND NO SOONER... actually implement this method.

3 dự án cuối cùng tôi làm việc tôi đã dành vài ngày cho mỗi lần loại bỏ lỗi thời, sai lệch và chỉ là những bình luận vô dụng đơn giản từ cơ sở mã. Nếu có thể và cần thiết, tôi thay thế chúng bằng những bình luận phù hợp hơn, nhưng thường xuyên hơn không chỉ là câu hỏi xóa bình luận và tiếp tục.

Tôi đã làm tương tự như vậy trên hầu hết các cơ sở mã hóa mà tôi từng tiếp quản từ người khác, thường là sau khi nó không được làm rõ trong một thời gian và chủ sở hữu ban đầu đã qua lâu và / hoặc không muốn hoặc không có khả năng thực hiện chuyển giao đúng cách.

Nó có thể là sự suy giảm trong việc sử dụng các ý kiến. Bao nhiêu mã của bất cứ ai đủ điều kiện? Đối với một, ai đó thực sự phải bao gồm các ý kiến ​​cho họ đã lỗi thời. Thứ hai, mã đã được nhận xét phải được thay đổi. Không chắc chắn tỷ lệ phần trăm cao của mã đủ điều kiện.

Bạn chỉ cần dựa vào một bình luận xấu để làm hỏng một phần lớn của một ứng dụng và lãng phí rất nhiều thời gian của bạn.

Trong một tổ chức tạo ra rất nhiều mã, rất khó để giữ các bình luận đồng bộ. Cách tốt nhất để hiểu những gì đang xảy ra là sử dụng các phần mềm vẽ sơ đồ luồng điều khiển của mô-đun mà bạn đang làm việc. Đó là cách duy nhất để giữ cảm giác về những gì phần mềm làm.