Chia sẻ mã phân tích: viết mã để người khác đọc được, vì người đó là bạn sau sáu tháng

Lý do thường được nêu để chia sẻ mã là minh bạch. Lý do thực tế hơn: mã chỉ mình bạn hiểu là mã bạn cũng sẽ không hiểu vào tháng thứ tám, khi phản biện hỏi một câu về bước thứ ba.

Viết mã cho người khác đọc được chính là viết cho bạn của sáu tháng sau.

Chuẩn bị trước khi chia sẻ

• Bỏ hết đường dẫn tuyệt đối trên máy bạn.
• Bỏ khoá, mật khẩu, thông tin nhận dạng.
• Ghi rõ phiên bản phần mềm và thư viện.
• Thêm tệp hướng dẫn cách chạy.
• Chạy thử trên máy khác.

Tệp hướng dẫn cần gì

• Cần dữ liệu gì, lấy ở đâu.
• Chạy tệp nào, theo thứ tự nào.
• Kết quả ra ở đâu.
• Mất bao lâu để chạy hết.
• Năm dòng này quyết định mã của bạn có dùng được không.

Viết mã cho người đọc

• Tên biến có nghĩa, không viết tắt bí ẩn.
• Ghi chú giải thích vì sao, không giải thích cái gì.
• Tách thành các bước rõ ràng.
• Ghi chú ở chỗ bạn đã quyết định một điều không hiển nhiên.

Nếu không chia sẻ được toàn bộ

• Chia sẻ mã ngay cả khi dữ liệu bị hạn chế.
• Kèm dữ liệu mẫu giả để chạy thử.
• Mã không có dữ liệu vẫn cho biết bạn đã làm gì.

Nơi chia sẻ

• Kho mã có đánh dấu bản phát hành và cấp định danh.
• Dẫn định danh đó trong bài.
• Đừng chỉ để trên trang cá nhân.

Một điều đáng nhớ

Viết ghi chú giải thích vì sao, không giải thích cái gì.

Người đọc mã thấy được nó đang làm gì. Cái họ không thấy được — và cái bạn cũng sẽ quên — là vì sao bạn chọn ngưỡng đó, vì sao loại nhóm kia, vì sao không dùng cách hiển nhiên hơn.

Câu hỏi thường gặp