Làm thế nào tôi có thể đối phó với một thành viên trong nhóm không thích bình luận trong mã?

Một trong những thành viên trong nhóm của tôi luôn tránh đưa ra nhận xét trong mã của anh ấy.

Mã của anh ấy không phải là tài liệu tự, và các lập trình viên khác gặp khó khăn trong việc hiểu mã của anh ấy.

Tôi đã yêu cầu anh ta nhiều lần để nhận xét mã của anh ta, tuy nhiên anh ta chỉ đưa ra lời bào chữa hoặc tuyên bố rằng anh ta sẽ làm điều đó sau. Mối quan tâm của ông là việc thêm ý kiến ​​sẽ mất quá nhiều thời gian và trì hoãn các dự án.

Lập luận nào tôi có thể trình bày với anh ấy để thuyết phục anh ấy viết đúng mã của mình?

Về lưu ý đó, tôi có sai khi tập trung vào các bình luận mã hay đây là dấu hiệu của một vấn đề lớn hơn cần được giải quyết?

Nhận xét một mình không tạo ra mã tốt hơn và chỉ cần đưa ra "nhiều bình luận" có thể sẽ cung cấp cho bạn ít hơn so với /* increment i by 1 */nhận xét về phong cách.

Vì vậy, hãy tự hỏi tại sao bạn muốn những ý kiến. "Đó là cách thực hành tốt nhất" không được tính là một đối số trừ khi bạn hiểu tại sao.

Bây giờ, lý do nổi bật nhất để sử dụng các bình luận là để mã dễ hiểu hơn và khi mọi người phàn nàn về việc thiếu bình luận, họ là những con vẹt không biết gì hoặc họ khó hiểu được mã họ đang làm việc.

Vì vậy, đừng phàn nàn về những bình luận bị thiếu: phàn nàn về mã không thể đọc được. Hoặc tốt hơn nữa, đừng phàn nàn, hãy tiếp tục đặt câu hỏi về mã. Đối với bất cứ điều gì bạn không hiểu, hãy hỏi người đã viết nó. Dù sao bạn cũng nên làm điều đó; với mã không thể đọc được, bạn sẽ chỉ hỏi thêm câu hỏi. Và nếu bạn quay lại một đoạn mã sau đó và bạn không chắc bạn nhớ chính xác nó làm gì, hãy hỏi lại câu hỏi tương tự.

Nếu các bình luận có thể khắc phục nó và đồng nghiệp của bạn có bộ não hoạt động, đôi khi anh ấy / cô ấy sẽ nhận ra rằng việc bình luận mã dễ dàng hơn nhiều so với việc bạn luôn luôn hỏi những câu hỏi ngu ngốc. Và nếu bạn không thể đưa ra câu hỏi, thì có lẽ mã đó đã hoàn toàn có thể đọc được và chính bạn là người có lỗi - sau tất cả, không phải tất cả các mã đều cần bình luận.

Về mặt kỹ năng con người, tránh nghe có vẻ ủy khuất hoặc buộc tội bằng mọi giá; nghiêm túc và trung thực về câu hỏi của bạn.

Tôi đã gặp rất nhiều nhà phát triển gặp khó khăn trong việc viết mã tự viết tài liệu hoặc nhận xét hữu ích. Những loại người này thường thiếu đủ kỷ luật hoặc kinh nghiệm để làm điều đó đúng.

Điều không bao giờ làm việc là "bảo họ thêm bình luận". Điều này sẽ không tăng kỷ luật tự giác hoặc kinh nghiệm của họ. IMHO điều duy nhất có thể hoạt động là thực hiện các phiên đánh giá và tái cấu trúc mã thường xuyên. Khi một nhà phát triển đã hoàn thành một nhiệm vụ, hãy cho phép anh ấy / cô ấy giải thích bất kỳ phần nào của mã mà bạn không hiểu. Ngay lập tức tái cấu trúc hoặc ghi lại mã theo cách mà cả hai bạn sẽ hiểu 6 tháng sau.

Làm điều này trong khoảng thời gian vài tháng, ít nhất hai lần một tuần. Nếu bạn đủ may mắn, các nhà phát triển khác sẽ tìm hiểu qua các phiên này để bạn có thể giảm tần suất xem xét.

Tôi ngạc nhiên không ai đã đề cập đến đánh giá mã chưa. Làm mã đánh giá! Khi anh ấy kiểm tra chất lượng kém, đừng nói "thêm ý kiến". Liên tục đặt câu hỏi và yêu cầu anh ấy cho bạn biết mã của anh ấy làm gì và tại sao. Ghi chép. Sau đó, vào cuối bài đánh giá mã, đưa cho anh ta một bản ghi chú và bảo anh ta làm cho câu hỏi của bạn khá rõ ràng. Bằng cách thêm ý kiến ​​hoặc chỉ bằng cách cấu trúc lại mã của mình để làm cho nó có chất lượng tốt hơn (tốt nhất là sau này khi có thể)

Điều này phụ thuộc vào mã mà nhân viên nhóm của bạn tạo ra. Nếu bạn đọc cuốn sách Clean Code từ chú Bob, bạn sẽ thấy rằng ông thực sự thích không thêm ý kiến ​​vào mã. Nếu bản thân mã là có thể đọc được như nó cần, thì hầu như không cần bình luận.

Nếu đó không phải là trường hợp, hoặc bạn yêu cầu bình luận do một số chính sách không thể thương lượng, thì câu hỏi chính là liệu chỉ có bạn muốn anh ấy / cô ấy viết bình luận, hay đó là toàn bộ nhóm hay nhóm / dự án lãnh đạo. Nếu đó chỉ là bạn, thì bạn nên nói chuyện với các đồng nghiệp khác để tìm hiểu lý do tại sao nó có thể không phải là một vấn đề lớn như vậy.

Nếu người lãnh đạo dự án thiếu các bình luận, bạn cũng có thể yêu cầu họ như một phần của sự hoàn chỉnh , tức là nếu mã được gửi thiếu bình luận thì công việc vẫn chưa kết thúc. Anh ta có thể không tiếp tục làm công việc khác, cho đến khi công việc hiện tại của anh ta kết thúc và cho những bình luận đó là bắt buộc. Tuy nhiên, hãy nhớ rằng loại cưỡng bức này rất có thể sẽ dẫn đến những bình luận khủng khiếp (mong đợi vô số lời bình luận lặp đi lặp lại của mã).

Cách khả thi duy nhất theo quan điểm khiêm tốn của tôi là thảo luận về lợi nhuận thực tế mà bạn và mọi người khác nhận được từ các bình luận. Nếu anh ấy không hiểu nó chỉ bằng thảo luận, thì luôn luôn có một cách khó khăn: thay vì để họ viết mã mới, họ sẽ làm việc với mã hiện có. Nếu có thể, bạn nên tìm cho họ hai lĩnh vực công việc khác nhau - một khu vực có bình luận hữu ích phù hợp và khu vực khác thiếu ý kiến. Phải đọc mã không bình luận không thể đọc được của người khác là một cái mở mắt liên quan đến công việc của bạn.

Chúng tôi đã từng ở đó một lần và tức giận vì tác giả ban đầu của một số nguồn vì làm việc rất cẩu thả. Đó là sự phản ánh bổ sung rằng mỗi chúng ta đều là một tác giả như vậy cũng khiến bạn nhận ra rằng bạn nên quan tâm đến khả năng đọc - do đó, đừng quên thảo luận về kết quả với đồng nghiệp của bạn sau đó để thúc đẩy phản ánh này.

Nếu bạn có một nhân viên không thể làm theo hướng dẫn, hãy khiển trách anh ta và chắc chắn rằng điều đó sẽ không giúp ích cho sự nghiệp của anh ta. Sự nhất quán trong phong cách mã hóa là rất quan trọng đối với một nhóm và nếu mọi người khác đang viết bình luận và điều này thì không, điều đó sẽ làm tổn thương phong cách mã hóa.

Điều đó nói rằng, bạn có thể có thể giúp anh ta ra. Theo kinh nghiệm của tôi, khi ai đó phản đối việc bình luận mất quá nhiều thời gian, có một rào cản tâm lý như là

1. Anh ta tự giác về các lựa chọn thiết kế / mã của mình và không muốn trình bày chúng trong văn xuôi. (Đánh giá mã có thể hữu ích để củng cố sự tự tin của ai đó cũng như phá vỡ chúng.)
2. Anh ấy làm việc rất tuyến tính và không suy nghĩ nhiều. Nhận xét là đau đớn vì nó buộc anh ta phải dỡ bỏ mã ngay lập tức mà anh ta sắp viết từ bộ nhớ làm việc của mình để soạn thảo ý định của mình theo một cách khác. (Nếu điều này là đúng, việc bình luận trở nên rất quan trọng đối với chất lượng mã của anh ấy.)
3. Trong lịch sử mọi người không hiểu ý kiến ​​của ông.

Điều quan trọng đối với một lập trình viên là nhận ra rằng các nhận xét giống như các bài kiểm tra: Chúng không chỉ để sử dụng trong tương lai - Chúng dành cho chính lập trình viên. Họ buộc anh phải suy nghĩ khác về cách tiếp cận của mình.

Không ai trong số này là thay thế cho CI, kiểm tra hoặc đánh giá mã. Nó chỉ là một trong nhiều phần quan trọng của mã hóa, bản thân nó, không viết mã.

Nhận phần mềm xem xét mã, và sử dụng nó tốt.

Chúng tôi sử dụng Kiln, và chúng tôi yêu nó. Chúng tôi có một chính sách rằng mọi thay đổi phải được xem xét (mặc dù chúng tôi cho phép các nhà phát triển nâng cao / phê duyệt đánh giá cho chính họ trên các thẻ và sáp nhập không xung đột (mặc dù hầu hết chúng tôi sử dụng rebaseif);

Mã không rõ ràng là lý do để đánh giá mã bị từ chối. Việc sửa lỗi là bình luận hay mã rõ ràng hơn không quan trọng, nhưng người đánh giá phải có khả năng hiểu nó. Một số nhà phát triển thích viết lại mã, nhưng những người khác (bao gồm cả tôi) thường thấy việc thể hiện ý định trong bình luận dễ dàng hơn (mã có thể dễ dàng hiển thị những gì nó làm, nhưng khó hơn để hiển thị những gì nên làm).

Nếu có câu hỏi nào về tính rõ ràng của mã, người đánh giá luôn thắng. Tất nhiên tác giả hiểu nó, bởi vì họ đã viết nó. Nó cần phải rõ ràng với người khác.

Bằng cách sử dụng phần mềm như Kiln, không có thay đổi nào bị bỏ qua. Mọi người trong nhóm dev của tôi thích nó theo cách này. Phần mềm đánh giá mã đã có tác động rất lớn đến cả chất lượng mã và chất lượng ứng dụng của chúng tôi :-)

Thật dễ dàng để các nhà phát triển có thể phòng thủ với các đánh giá bị từ chối khi lần đầu tiên giới thiệu phần mềm, nhưng theo kinh nghiệm của tôi, họ không mất nhiều thời gian để nhận ra mọi thứ tốt hơn theo cách này và nắm lấy nó :-)

Chỉnh sửa: Cũng đáng chú ý, chúng tôi cố gắng không để các nhà phát triển giải thích mã mật mã bằng lời nói hoặc trong các nhận xét trong đánh giá. Nếu một cái gì đó không rõ ràng, nơi tốt nhất để giải thích nó là trong mã (trong các bình luận, hoặc bằng cách tái cấu trúc), sau đó thêm các thay đổi mới vào cùng một đánh giá.

Thật thú vị, khả năng đọc như được áp dụng cho ngôn ngữ tự nhiên được đo bằng tốc độ đọc và hiểu. Tôi đoán một quy tắc đơn giản có thể thực sự được thông qua, nếu một nhận xét mã cụ thể không cải thiện thuộc tính này, nó có thể tránh được .

Tại sao ý kiến?

Mặc dù, nhận xét mã là một dạng tài liệu nhúng, có nhiều cách trong các ngôn ngữ lập trình cao cấp để tránh lập trình "thừa tài liệu" (mã có ý nghĩa) bằng cách sử dụng các yếu tố của chính ngôn ngữ. Cũng là một ý tưởng tồi khi biến mã thành danh sách từ sách giáo khoa lập trình, trong đó các câu lệnh riêng lẻ được giải thích theo nghĩa đen gần như theo kiểu tautological (nhớ ví dụ "/ * i tăng 1 * /" trong các câu trả lời đã được cung cấp), làm cho các nhận xét đó có liên quan chỉ để lập trình viên thiếu kinh nghiệm với ngôn ngữ.

Tuy nhiên, đó là ý định cố gắng bình luận mã "dưới tài liệu" (nhưng vô nghĩa) thực sự là "nguồn gốc của mọi tội lỗi". Chính sự tồn tại của mã "dưới tài liệu" là tín hiệu xấu - hoặc đó là một mớ hỗn độn không có cấu trúc, hoặc hack lập dị của mục đích bị mất bí ẩn. Rõ ràng, giá trị của mã như vậy ít nhất là nghi vấn. Thật không may, luôn có những ví dụ, khi thực sự tốt hơn là đưa một nhận xét vào một phần của các dòng mã được định dạng (được nhóm trực quan) hơn là bọc nó vào chương trình con mới (nhớ "tính nhất quán ngu ngốc" mà "là hobgoblin của những bộ óc nhỏ") .

Mã dễ đọc! = Nhận xét mã

Mã có thể đọc được không yêu cầu chú thích bằng bình luận. Ở mỗi vị trí cụ thể trong mã luôn có bối cảnh của một nhiệm vụ mà mã cụ thể này được cho là phải đạt được. Nếu mục đích bị thiếu và / hoặc mã làm điều gì đó bí ẩn = tránh nó bằng mọi giá. Không cho phép các bản hack lạ để điền mã của bạn - đó là kết quả trực tiếp của việc kết hợp các công nghệ lỗi với việc thiếu thời gian / sở thích để hiểu các nền tảng. Tránh mã bí ẩn trong dự án của bạn!

Mặt khác, chương trình Readable = code + tài liệu có thể chứa nhiều phần bình luận hợp pháp, ví dụ để tạo điều kiện cho việc tạo tài liệu "nhận xét cho API".

Thực hiện theo tiêu chuẩn kiểu mã

Thật buồn cười, câu hỏi không phải là lý do tại sao để bình luận mã, mà là về công việc nhóm - làm thế nào để sản xuất mã theo phong cách đồng bộ hóa cao (mà mọi người khác có thể đọc / hiểu). Bạn đang theo bất kỳ tiêu chuẩn phong cách mã trong công ty của bạn? Mục đích chính của nó là để tránh viết mã yêu cầu tái cấu trúc, quá "cá nhân" và "chủ quan" mơ hồ. Vì vậy, tôi đoán, nếu người ta thấy sự cần thiết trong việc sử dụng kiểu mã, thì có rất nhiều công cụ làm thế nào để thực hiện nó đúng cách - bắt đầu bằng việc giáo dục mọi người và kết thúc bằng tự động hóa để kiểm soát chất lượng mã (nhiều gợi ý, v.v.) và (sửa đổi kiểm soát tích hợp) hệ thống xem xét mã.

Trở thành một nhà truyền giáo dễ đọc mã

Nếu bạn đồng ý rằng mã được đọc thường xuyên hơn nó được viết. Nếu việc thể hiện rõ ràng ý tưởng và suy nghĩ rõ ràng là quan trọng đối với bạn, bất kể ngôn ngữ nào được sử dụng để giao tiếp (toán học, mã máy hoặc tiếng Anh cũ) .. Nếu nhiệm vụ của bạn là xóa bỏ lối suy nghĩ thay thế buồn tẻ và xấu xí .. (xin lỗi , cái cuối cùng là từ một "bảng kê khai" khác) .. đặt câu hỏi, bắt đầu thảo luận, bắt đầu truyền bá suy nghĩ kích thích sách về làm sạch mã (có lẽ không chỉ là thứ tương tự như mẫu thiết kế của Beck, mà giống như RC Martin đã đề cập ) trong lập trình. Hơn nữa đi qua một loạt các ý tưởng quan trọng (trích từ cuốn sách O'Reilly về khả năng đọc)

• Đơn giản hóa việc đặt tên, nhận xét và định dạng bằng các mẹo áp dụng cho mọi dòng mã
• Tinh chỉnh các vòng lặp, logic và các biến của chương trình để giảm độ phức tạp và nhầm lẫn
• Các vấn đề tấn công ở cấp độ chức năng, chẳng hạn như sắp xếp lại các khối mã để thực hiện một nhiệm vụ tại một thời điểm
• Viết mã kiểm tra hiệu quả, kỹ lưỡng và ngắn gọn cũng như dễ đọc

Cắt "bình luận" ra, người ta vẫn còn rất nhiều (tôi đoán viết mã không cần bình luận là một phần của bài tập tuyệt vời!). Đặt tên định danh có ý nghĩa về mặt ngữ nghĩa là một khởi đầu tốt. Tiếp theo, cấu trúc mã của bạn bằng cách nhóm các hoạt động được kết nối logic vào các hàm và lớp. Và như vậy. Một lập trình viên tốt hơn là một nhà văn tốt hơn (tất nhiên, giả sử các kỹ năng kỹ thuật khác được đưa ra).

Tôi có sai khi tập trung vào các bình luận mã hay đây là dấu hiệu của một vấn đề lớn hơn cần được giải quyết?

Một chút nào đó. Mã lớn không cần bình luận. Tuy nhiên như bạn đã nói, mã của anh ấy không phải là tài liệu tự. Vì vậy, tôi sẽ không tập trung vào các ý kiến. Bạn nên tập trung vào việc cải thiện kỹ năng và tay nghề của các nhà phát triển của bạn.

Vậy làm thế nào để làm điều đó? Đề xuất của Doc Brown về các phiên đánh giá / tái cấu trúc là một ý kiến ​​hay. Tôi thấy lập trình cặp thậm chí hiệu quả hơn, nhưng nó cũng có thể khó thực hiện hơn đáng kể.

Trước hết, tôi sẽ đề nghị bạn giải quyết lại cách tiếp cận của bạn về các ý kiến.

Nếu chúng là các nhận xét tài liệu ở cấp API (được hiển thị sau công khai), thì nhà phát triển này chỉ đơn giản là không thực hiện công việc của mình. Nhưng đối với tất cả các ý kiến ​​khác, hãy cẩn thận.

Trong hầu hết các trường hợp tôi gặp phải chúng, ý kiến ​​là xấu xa. Tôi khuyên bạn nên đọc chương bình luận mã của "Clean code" của Robert Martin để hiểu rõ lý do tại sao.

Nhận xét làm tổn thương mã của bạn theo nhiều cách:

1) Chúng khó bảo trì. Bạn sẽ phải làm thêm khi tái cấu trúc; nếu bạn thay đổi logic được mô tả trong bình luận, bạn cũng cần chỉnh sửa nhận xét.

2) Họ thường nói dối. Bạn không thể tin tưởng bình luận và phải đọc mã thay thế. Điều này đặt ra câu hỏi: tại sao bạn cần bình luận?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(Băm không phải là tổng mà là sản phẩm.)

3) Nhận xét làm lộn xộn mã, và rất hiếm khi thêm bất kỳ giá trị nào.

Giải pháp của tôi: Thay vì thêm nhiều bình luận, hãy cố gắng loại bỏ chúng!

Nếu một thành viên trong nhóm gặp khó khăn trong việc hiểu mã của thành viên nhóm khác (vì bất kỳ lý do nào); sau đó thành viên trong nhóm sẽ có thể tìm ra ai đã viết mã gốc (bất kỳ hệ thống kiểm soát sửa đổi lành mạnh nào) và nên được yêu cầu tác giả của mã giải thích trực tiếp (ví dụ: đi bộ đến bàn của họ, ngồi xuống và thảo luận về nó).

Trong trường hợp này, nếu thiếu bình luận là một vấn đề thì người không bình luận đầy đủ mã của họ sẽ dành một lượng lớn thời gian để giải thích những gì họ đã làm; và (nếu họ thông minh) sẽ bắt đầu thêm nhận xét để tránh mất thời gian cho tất cả những giải thích đó.

Lưu ý rằng việc khuyến khích các thành viên trong nhóm hỏi nhau để giải thích là có giá trị vì những lý do khác. Ví dụ, có thể một thành viên trong nhóm ít kinh nghiệm hơn và có thể học hỏi những điều từ các thành viên nhóm có kinh nghiệm hơn.

Hầu hết, bằng cách khuyến khích các thành viên trong nhóm hỏi nhau để giải thích bạn tạo ra một hệ thống tự cân bằng; nơi các thành viên nhóm khác nhau "tự động điều chỉnh" với nhau.

Đây phần lớn là một phần mở rộng của câu trả lời tdammers, nhưng thực hiện đánh giá mã theo định kỳ.

Để anh ấy (và các nhà phát triển khác) ngồi xuống, xem mã của họ và ít nhiều bảo vệ trước cấp trên và đồng nghiệp của họ sẽ khiến mọi người trở thành lập trình viên tốt hơn và sẽ thêm giá trị thực trong một khoảng thời gian tương đối ngắn. Trong ngắn hạn, nó sẽ cung cấp cho nhà phát triển trong câu hỏi không có lý do gì, tại thời điểm xem xét, nhận xét đúng mã của mình.

EDIT: Tôi không chắc tại sao ai đó lại đánh giá thấp đề xuất của tôi - có lẽ tôi đã cho rằng lợi ích của việc xem xét mã sẽ là kiến ​​thức phổ biến ... vui lòng xem chủ đề này để phân tích cộng đồng về thực tiễn:

Là mã xem xét thực hành tốt?

Xem xét các quan điểm thường cực đoan về bình luận, tôi ngần ngại cân nhắc. Điều đó đang được nói ...

Một số đối số mà tôi có thể trình bày là nếu bạn định viết mã (không thể đọc được) thì nó phải được ghi lại đúng cách?

Hiểu cách viết mã duy trì và có thể đọc được cần có thời gian, thực hành và kinh nghiệm. Các lập trình viên thiếu kinh nghiệm (và đáng buồn là nhiều người có kinh nghiệm) thường phải chịu Hiệu ứng Ikea ( PDF ). Đó là bởi vì họ đã xây dựng nó và quen thuộc với nó, và họ chắc chắn rằng mã không chỉ tuyệt vời mà còn có thể đọc được.

Nếu người đó là một lập trình viên tuyệt vời, thì rất ít nếu có bất kỳ tài liệu nào được yêu cầu. Tuy nhiên, hầu hết các lập trình viên không tuyệt vời và rất nhiều mã của họ sẽ bị ảnh hưởng trong bộ phận "khả năng đọc". Yêu cầu lập trình viên tầm thường hoặc đang phát triển "giải thích mã của họ" là hữu ích ở chỗ nó buộc họ phải xem mã của họ với con mắt quan trọng hơn.

Điều này có nghĩa là "tài liệu" mã của họ? Không cần thiết. Trường hợp cụ thể, tôi đã có một lập trình viên tương tự với vấn đề này trong quá khứ. Tôi buộc anh phải làm tài liệu. Thật không may, tài liệu của anh ta không thể mã hóa như mã của anh ta và không thêm bất cứ thứ gì. Nhìn lại mã đánh giá sẽ có ích hơn.

Bạn (hoặc một đại biểu) nên ngồi xuống với lập trình viên này và lấy một số mã cũ của anh ta. Không phải những thứ mới anh ấy biết từ chỉ làm việc trên nó. Bạn nên yêu cầu anh ấy dẫn bạn qua mã của anh ấy với sự tương tác tối thiểu. Đây cũng có thể là một phiên "tài liệu" riêng biệt, nơi anh sẽ giải thích bằng cách viết mã của mình. Sau đó, anh ta nên nhận được phản hồi về cách tiếp cận tốt hơn.

Như một bên ... đôi khi một số tài liệu là cần thiết cho dù mức độ "dễ đọc" của mã tốt đến mức nào. API nên có tài liệu, các hoạt động cực kỳ kỹ thuật và phức tạp nên có tài liệu để hỗ trợ lập trình viên hiểu các quy trình liên quan (thường nằm ngoài miền kiến ​​thức của lập trình viên) và một số điều như các biểu thức phức tạp thực sự sẽ ghi lại những gì bạn phù hợp với.

Nhiều dự án yêu cầu tài liệu mã: tài liệu giao diện, tài liệu thiết kế, ...

Một số dự án yêu cầu tài liệu đó phải được đưa vào nhận xét mã và trích xuất bằng các công cụ như Doxygen hoặc Sphinx hoặc Javadoc, để mã và tài liệu phù hợp hơn.

Bằng cách đó, các nhà phát triển được yêu cầu viết bình luận hữu ích trong mã và nhiệm vụ này được tích hợp trong kế hoạch dự án.

Tôi sẽ nói rõ hầu hết các câu trả lời và ý kiến ​​gợi ý: có lẽ bạn cần tìm ra vấn đề thực sự ở đây thay vì cố gắng đưa giải pháp nhận thức của bạn đi qua.

Bạn có động lực để xem ý kiến ​​trong mã của mình; tại sao ? Bạn đã đưa ra một lý do; Tại sao lý do đó rất quan trọng với bạn? Anh ấy có động lực hơn để làm một cái gì đó khác thay vào đó; tại sao ? Anh ta sẽ đưa ra một lý do; Tại sao lý do đó rất quan trọng với anh ta? Lặp lại điều này cho đến khi bạn đạt đến mức độ xung đột thực sự phát sinh và cố gắng tìm giải pháp mà cả hai bạn có thể sống cùng. Tôi cá là nó có rất ít liên quan đến việc bình luận.

Nếu bạn tuân theo tiêu chuẩn mã hóa tốt, sẽ có một số lượng bình luận tối thiểu cần thiết. quy ước đặt tên là quan trọng. Tên phương thức và tên biến sẽ mô tả vai trò của chúng ..

TL của tôi đề nghị tôi sử dụng ít bình luận hơn. anh ta muốn mã của tôi nên dễ hiểu và tự mô tả. ví dụ đơn giản: tên biến cho loại chuỗi được sử dụng cho mẫu tìm kiếm

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

Yêu các câu trả lời xem lại mã, nhưng có lẽ quá trình của tôi cũng sẽ giúp một chút.

Tôi thích bình luận, nhưng tôi gần như không bao giờ thêm chúng vào mã trong lần đầu tiên. Có thể đó chỉ là phong cách của tôi nhưng tôi sẽ nhấn cùng một đoạn mã từ 3 đến 5 lần trong quá trình phát triển (tái cấu trúc, kiểm tra viết, v.v.).

Bất cứ khi nào tôi cảm thấy hơi bối rối hoặc bất cứ khi nào ai đó hỏi tôi một câu hỏi về một phần của mã, tôi cố gắng sửa nó để nó có ý nghĩa.

Điều này có thể đơn giản như việc thêm một bình luận loại bỏ một tập hợp các thao tác khó hiểu vào hàm riêng của chúng hoặc nó có thể kích hoạt một bộ tái cấu trúc lớn hơn như trích xuất một đối tượng mới.

Tôi khuyên bạn nên khuyến khích mọi người trong nhóm "sở hữu" rằng mã của họ có thể đọc được cho người khác - điều này có nghĩa là mỗi khi ai đó hỏi bạn một câu hỏi về mã của bạn, bạn cam kết thực hiện thay đổi - hoặc tốt hơn là kết hợp với điều đó người để thực hiện thay đổi ngay sau đó!

Nghiêm túc xem xét thúc đẩy điều này như là một phần của "Hợp đồng nhóm" của bạn (Và chắc chắn tạo ra một hợp đồng nếu bạn không có) - theo cách đó mọi người đã đồng ý và bạn đặt nó lên một bức tường ở đâu đó để không có bất kỳ câu hỏi về những gì bạn đã đồng ý làm.

Có lẽ anh chàng này cần được đánh giá cao về kỷ luật mã hóa tốt, và tại sao điều quan trọng đối với người khác là có thể hiểu được mã anh ta viết.

Tôi đã làm việc trên một số cơ sở mã hóa thực sự khủng khiếp trong sự nghiệp của mình, những nơi mà mã được tổ chức rất tệ, tên biến rất kém, nhận xét quá tệ hoặc không tồn tại, rằng cơ sở mã hóa đã làm tổn hại đến năng suất của tôi. Bạn không thể làm việc để sửa chữa hoặc cải thiện một cơ sở mã mà bạn không hiểu và nếu nó được viết theo cách không thể chấp nhận được đối với người mới thì họ sẽ dành nhiều thời gian để cố gắng hiểu nó hơn là thực sự làm việc với nó.

Không có giáo viên tốt hơn kinh nghiệm khắc nghiệt!

Mỗi codebase đều có một số bit khủng khiếp ẩn giấu trong đó, các bộ phận của hệ thống không ai muốn chạm vào vì họ sợ phá vỡ thứ gì đó hoặc họ không thể thực hiện bất kỳ công việc có ý nghĩa nào vì bất cứ ai đã viết mã đã rời đi từ lâu và hiểu được của mã với họ. Nếu mã đó không bị lỗi và không tự ghi lại thì nó chỉ làm cho vấn đề tồi tệ hơn.

Tôi đề nghị bạn nên tìm một chút về cơ sở mã của bạn giống như vậy và giao trách nhiệm cho người viết mã rắc rối của bạn cho nó. Trao cho anh ta quyền sở hữu nó, biến nó thành trách nhiệm của anh ta, để anh ta học được nỗi đau thực sự khi làm việc với mã không thể được duy trì bởi vì nó không được ghi chép tốt hoặc không thể hiểu trong một khoảng thời gian ngắn. Sau vài tháng làm việc với nó, tôi chắc chắn anh ấy sẽ bắt đầu quay lại.

Đưa cho anh ta một số mã khác mà không có ý kiến ​​và yêu cầu anh ta hiểu mã. Có thể là anh hiểu tầm quan trọng của những bình luận thích hợp rồi.

Có lập trình viên này làm một số bảo trì mã. Nếu không, anh ta nên: kiểm tra bất kỳ dự án không thích nào bạn có xung quanh và giao bảo trì cho anh ta.

Thông thường đó là những dự án được ghi chép kém mà bạn mất hàng giờ cố gắng để hiểu những gì đang diễn ra để sửa những gì có thể dễ dàng sửa chữa. Nếu loại kinh nghiệm này không khiến anh ấy muốn cập nhật, tài liệu chính xác và hữu ích sẽ không có gì.

Trong một trong những dự án trước đây của tôi đã thiếu hàng tá ý kiến ​​(thuật toán, kết quả hoặc một số JavaDoc cơ bản), vì vậy tôi chỉ quyết định thực hiện 130 vấn đề cho anh ấy, thông báo qua email về mỗi vấn đề cứ sau 4 ngày. Sau 3 tuần anh ấy có 280 vấn đề, sau đó anh ấy quyết định viết bình luận.

Nhận xét có một mục đích và chỉ một mục đích:

Tại sao mã này làm điều này?

Nếu một bình luận không giải thích tại sao một cái gì đó là như vậy, thì nó nên được gỡ bỏ. Những bình luận vô dụng làm lộn xộn mã ít hơn vô dụng, chúng có hại tích cực.

Tôi có thói quen biến nhận xét của mình thành điều rõ ràng nhất trong IDE của mình. Chúng được làm nổi bật với văn bản màu trắng trên nền màu xanh lá cây. Việc thực sự thu hút sự chú ý của bạn.

Điều này là do mã giải thích những gì đang làm, và các ý kiến ​​cho lý do tại sao nó đang làm điều đó. Tôi không thể nhấn mạnh điều này đủ.

Một ví dụ điển hình của một bình luận:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Một ví dụ tồi:

/* instantiate clsUser */

Nếu bạn đang sử dụng các nhận xét dưới dạng "các phần" của mã: Cắt phương thức voi ma mút của bạn thành các hàm có tên nhỏ hơn, hữu ích và xóa các nhận xét.

Nếu bạn đang nói những gì bạn đang làm trên dòng tiếp theo: Làm cho mã tự giải thích và xóa nhận xét.

Nếu bạn đang sử dụng nhận xét làm thông điệp cảnh báo: Hãy chắc chắn rằng bạn nói lý do tại sao.

Để bổ sung các câu trả lời ở đây, tôi có thể thêm "Nếu bạn muốn nó được thực hiện đúng, bạn phải tự làm nó."

Tôi không có nghĩa là trở thành "bình luận viên trưởng", ý tôi là trở thành một hình mẫu trong việc chứng minh những gì bạn muốn nhà phát triển khác này làm. Họ nói hiển thị là hiệu quả hơn so với nói . Nếu bạn có thể chứng minh lợi ích của các bình luận chất lượng, hoặc thậm chí là cố vấn cho nhà phát triển khác này (đến mức mà anh ta sẵn sàng), bạn có thể tìm thấy nhiều thành công hơn trong việc áp dụng nhận xét mã.

Tương tự, ở nhà có một số công việc gia đình tôi không quan tâm để làm. Tuy nhiên, những việc lặt vặt đó cũng là những việc vặt "thú cưng" của vợ tôi ... những việc lặt vặt phải được thực hiện để cô ấy được hạnh phúc. Tình huống tương tự áp dụng ngược lại. Tôi nghĩ rằng bạn có thể phải chấp nhận rằng nhà phát triển khác này có các ưu tiên khác với bạn và sẽ không đồng ý với bạn về mọi thứ. Giải pháp mà vợ tôi và tôi đã tìm thấy là đối với những việc lặt vặt "thú cưng" đó, chúng tôi chỉ phải tự làm chúng, ngay cả khi điều đó có nghĩa là tự mình làm thêm một chút.

Đơn giản: nếu nhân viên không đưa ra nhận xét, hãy bảo anh ta nhấn shift+alt+jđể nhận xét tự động theo từng phương pháp đồng thời với việc nhập mã. xin vui lòng sửa đổi mã để tránh những vấn đề này.