Làm thế nào để tôi tài liệu nhất thiết cấu trúc mã phức tạp?

Nếu tôi có một đoạn mã có tính toán học hoặc cấu trúc khá phức tạp và không thể sửa chữa được như vậy, thì tôi sẽ làm thế nào để ghi lại đoạn mã này? Cụ thể, làm thế nào tôi có thể đảm bảo rằng ai đó có thể không có các kỹ năng toán học hoặc kiến ​​trúc mà tôi làm có thể hiểu nó từ tài liệu? Tôi có nên ghi lại tất cả các môn toán không? Liên kết đến một hướng dẫn? Do một số liên kết hỗ trợ trực quan trong trường hợp cấu trúc phức tạp?

Điều này thực sự phụ thuộc vào mức độ phức tạp của mã và toán học. Bản thân mã phải - như mọi khi - phải tự viết tài liệu càng tốt. Đặt tên cho các biến chính xác, triển khai các phương thức logic và súc tích (chứ không phải các hàm mega), thêm tài liệu nội tuyến khi thích hợp (nghĩa là khi không rõ ràng mã đang thực sự làm gì).

Nếu bạn đang sử dụng một thuật toán không rõ ràng, hãy thêm một liên kết đến một tham chiếu đó là nguồn. Đây là một thực tiễn hợp lý vì nó cung cấp cho nhà phát triển một cách rất nhanh để tìm hiểu những gì bạn đang làm. Như tôi đã nói, điều này rất hữu ích nếu nó là một thuật toán không rõ ràng nhưng phức tạp. Điều này sẽ chứng minh rằng (a) bạn đang làm điều gì đó có ý nghĩa và (b) ai đó đã chứng minh rằng nó hoạt động.

Một ví dụ điển hình là một số công việc tôi đã làm xung quanh kết hợp văn bản mờ. Tôi đã nghiên cứu đáng kể về các thuật toán và thực hiện cái được gọi là 'Thuật toán Smith-Waterman' (thực sự được sử dụng cho các chuỗi DNA, nhưng áp dụng cho 'khớp' nói chung). Vì vậy, thay vì chỉ đơn giản là thực hiện thuật toán, tôi đã tìm thấy các tài liệu tham khảo trực tuyến và bao gồm một hoặc hai liên kết. Như trên, điều này chứng tỏ rằng (a) thuật toán của tôi phù hợp với thuật toán được xuất bản và (b) thuật toán đã được xem xét và hiển thị để hoạt động.

Tuy nhiên, điều này không nhất thiết giải thích cách thức hoạt động của mã và các lớp khác nhau phải làm gì. Khi bạn đi viết một số tài liệu 'thực' - hướng dẫn dành cho nhà phát triển hệ thống - bạn nên giải thích những gì bạn đã làm và cung cấp đủ thông tin cho hỗ trợ trong tương lai. Theo tôi tài liệu này nên được đọc bởi một người không biết kỹ thuật; nó không cần phải 'chết lặng' nhưng nó nên loại trừ biệt ngữ và không dựa vào kiến ​​thức giả định.

Bình luận xung quanh nguồn là điều đầu tiên bạn nên làm. Điều này đảm bảo rằng có một liên kết trực tiếp đến tài liệu ngay theo mã. Nếu tài liệu rất phức tạp, hãy xem xét chỉ đăng một bản tóm tắt trong các nhận xét và sau đó liên kết đến một số tài liệu bên ngoài có mô tả đầy đủ hơn về thuật toán kiến ​​trúc / phức tạp. Tuy nhiên, nếu nó không quá phức tạp, hãy cân nhắc bao gồm tất cả các tài liệu ở một nơi. Điều này sẽ tối đa hóa khả năng mã / tài liệu của bạn được đồng bộ hóa và được đọc cùng nhau.

Tài liệu mã đến mức mà nhóm / công ty của bạn cần nó. Nếu một jr. dev sẽ được yêu cầu để duy trì mã, bạn có thể phải đi vào chi tiết về một số phép toán. Đây là một quyết định quản lý và họ phải cung cấp cho bạn thời gian cần thiết.

Tôi không nghĩ rằng bạn phải ghi lại mã nhiều đến mức tài khoản của bạn bị thay thế bởi một nhà phát triển nhỏ hơn. Nếu đó là một mối quan tâm, bạn cần phải có thời gian để làm tài liệu.

Bạn không cần phải thực hiện tìm kiếm trên web cho họ.