Trình bày/giải thích mã và các quyết định thiết kế cho các thành viên trong nhóm

Question

Tôi đang làm việc trên một dự án mà tôi sẽ phải thường xuyên biện minh và giải thích các quyết định về mã và thiết kế của mình cho các thành viên nhóm không tham gia trực tiếp vào cùng khu vực của dự án là.

Làm cách nào để giải thích rõ nhất các quyết định thiết kế kỹ thuật của tôi cho các thành viên nhóm ở một vị trí khác? Các mã hướng dẫn có đáng để dành thời gian cho các thành viên trong nhóm không trực tiếp tham gia hay viết giải thích và mã được chú thích tốt hơn không? Nếu tôi quyết định đánh giá rất nhiều mã của mình để giải thích các quyết định thiết kế, thì tôi có nên làm điều đó trong một bản sao mã riêng biệt không?

Answer 1

Tôi thích sơ đồ đơn giản được vẽ bằng tay để giải thích thiết kế. Nhưng bạn phải giữ cho nó thực sự đơn giản, đừng quá tải nó với sơ đồ kiến ​​trúc đầy đủ và từng chi tiết nhỏ. Nói chuyện với các đồng nghiệp của bạn xung quanh biểu đồ sẽ làm cho nó trở thành một cuộc thảo luận tốt và nếu họ đặt câu hỏi về nó thì thời gian đáng giá hơn rất nhiều so với một bài phát biểu của riêng bạn.

Khi nói đến việc viết tư liệu mã, tôi là một người hâm mộ rất lớn của Bộ luật sạch. Nếu bạn cẩn thận đặt tên cho mọi thứ, bạn chỉ nên bỏ một dòng chú thích nếu có một quyết định thiết kế đằng sau mã khiến bạn chọn một cách không phổ biến. Tôi thường tránh rất nhiều tài liệu (như javadoc) trong mã của tôi.

Dưới đây là những gì tôi làm:

• giữ phương pháp đơn giản
• 1 mức độ chi tiết trong các phương pháp của bạn
• tên tốt cho các biến, phương pháp, các lớp học

Tôi cũng cố gắng tránh công cụ hackery trong mã của tôi. Nếu bạn cần giải thích một dòng trong mã của mình, bởi vì bạn đã sử dụng cách fanciest và ngắn nhất để làm mọi thứ, bạn có thể khiến The Next Developer phát điên.

Và, điều quan trọng: Cung cấp các trường hợp kiểm tra (có thể là kiểm thử đơn vị) cho mã của bạn, vì vậy các nhà phát triển khác có thể chạy chúng, xem điều gì xảy ra và thực sự xem cách mã của bạn được sử dụng để sử dụng. Tôi nghĩ rằng việc thử nghiệm các trường hợp như một cách để viết tư liệu cho mã của bạn là một cách thực sự tốt đẹp để các nhà phát triển khác làm quen với mã của bạn. Các quy tắc tương tự áp dụng cho các trường hợp kiểm tra so với mã của bạn: Làm cho nó sạch sẽ.

Answer 2

Thêm ý kiến ​​tốt để mã thực tế trong đó bao gồm những ví dụ ngắn, xem Alsos và vv
Hãy chắc chắn rằng bạn bao gồm sự giúp đỡ HTML được tạo ra trong kiểm tra-in kết quả
(làm cho các tài liệu dễ dàng hơn cho những người khác để truy cập).

Cũng bao gồm các dự án/gói demo trong giải pháp/dự án thể hiện những lợi thế của thiết kế của bạn và cách sử dụng mã của bạn.
Đảm bảo các ví dụ được kết nối với các chủ đề mà những người khác đang làm việc, điều này sẽ giúp họ kết nối dễ dàng hơn.

Answer 3

IMHO, nhận xét mã của bạn tốt có lẽ là cách tốt nhất để truyền đạt thông tin này. Tài liệu hướng dẫn lớn hoặc thậm chí tài liệu thiết kế đã lỗi thời nhanh chóng khi cơ sở mã phát triển. Bên cạnh đó, một lập trình viên ít có khả năng ngồi xuống và trang thông qua một hướng dẫn dày hơn để đi và poke xung quanh trong mã của bạn để tìm ra những gì đang xảy ra.

Nếu mã của bạn được thiết kế đủ rõ cấu trúc của nó là tự ghi lại, thì các nhận xét bạn thêm vào để giải thích thuật toán của bạn và sẽ cung cấp phần còn lại của thông tin mà các lập trình viên khác cần để hiểu mã của bạn.

Như đã đề cập, thật dễ dàng để trích xuất các nhận xét để tạo tài liệu API bằng nhiều ngôn ngữ. Đó là một điều hữu ích khác để làm.