Phần phương pháp viết “dữ liệu được phân tích bằng mô hình hỗn hợp tuyến tính trong R”. Một câu, trong khi đằng sau là 600 dòng mã với hàng chục quyết định: biến nào được chuẩn hoá, cấu trúc hiệu ứng ngẫu nhiên ra sao, xử lý mô hình không hội tụ thế nào. Không ai tái tạo được phân tích từ một câu. Mã chính là phần phương pháp đầy đủ.
Lý do phổ biến nhất để không chia sẻ mã là “mã của tôi xấu lắm”. Tin tốt: người đọc không cần mã đẹp, họ cần mã chạy được và hiểu được đủ để lần theo.
Ngưỡng đủ tốt để công bố
- Chạy từ đầu tới cuối trên dữ liệu (hoặc dữ liệu mô phỏng nếu dữ liệu thật không chia sẻ được).
- Tạo ra được bảng và hình trong bài, với tên file hoặc chú thích cho biết đoạn mã nào sinh ra bảng nào.
- Có README nói cần gì và chạy thế nào.
- Không chứa thông tin nhạy cảm.
Không cần: tối ưu tốc độ, viết lại thành gói phần mềm, bình luận từng dòng, kiểm thử tự động. Những thứ đó tốt nhưng không phải điều kiện để chia sẻ.
README tối thiểu
- Mô tả một câu: mã này tái tạo kết quả của bài báo nào (kèm DOI khi có).
- Yêu cầu: phần mềm và phiên bản (ví dụ R 4.4, các gói kèm phiên bản, hoặc file renv.lock / requirements.txt).
- Dữ liệu: lấy ở đâu, đặt vào thư mục nào. Nếu dữ liệu hạn chế, nói cách xin.
- Thứ tự chạy: 01_lam_sach → 02_mo_hinh → 03_bang_bieu, mỗi bước mất khoảng bao lâu.
- Ánh xạ kết quả: Bảng 2 do file 03 tạo, Hình 1 do file 04 tạo.
- Giấy phép và cách trích dẫn.
Mục ánh xạ kết quả hay bị quên nhưng giá trị nhất: người kiểm chứng thường chỉ quan tâm tới một bảng cụ thể.
Gỡ thứ không được lộ
Trước khi đẩy mã lên kho công khai, rà soát:
- Khoá API, mật khẩu cơ sở dữ liệu, token: chuyển vào biến môi trường hoặc file cấu hình không đưa lên kho. Nếu lỡ đẩy lên, xoá file là chưa đủ, vì lịch sử phiên bản vẫn giữ; phải đổi khoá ngay.
- Đường dẫn chứa tên người, tên máy: “/home/nguyenvana/…” vừa lộ thông tin vừa làm mã không chạy trên máy khác.
- Dữ liệu cá nhân bị nhúng trong mã: danh sách mã học sinh để lọc, ghi chú kiểu “loại em Lan vì nghỉ học”.
- File kết quả trung gian có thể chứa dữ liệu cấp cá nhân.
Một mẹo đơn giản: tạo một bản sao sạch của thư mục, xoá mọi thứ không cần, rồi chạy lại từ đầu. Nếu chạy được, đó là gói để công bố.
Chọn giấy phép
Mã không có giấy phép, về pháp lý, không cho ai quyền dùng lại. Lưu ý giấy phép Creative Commons được thiết kế cho nội dung và dữ liệu, không khuyến nghị cho mã.
| Giấy phép | Cho phép | Yêu cầu | Hợp khi |
|---|---|---|---|
| MIT | Dùng, sửa, phân phối, kể cả thương mại | Giữ thông báo bản quyền | Mã phân tích thông thường, muốn tối đa khả năng dùng lại |
| Apache 2.0 | Như MIT | Giữ thông báo, ghi thay đổi; có điều khoản về sáng chế | Phần mềm có thể liên quan tới sáng chế |
| GPL v3 | Dùng, sửa, phân phối | Bản phái sinh phải công bố mã theo cùng giấy phép | Muốn mọi cải tiến tiếp tục mở |
Kiểm tra chính sách sở hữu trí tuệ của trường và điều khoản của nhà tài trợ trước khi chọn; một số nơi có quy định riêng về phần mềm do nhân viên viết.
Nơi lưu: kho làm việc và bản lưu cố định
GitHub, GitLab là nơi làm việc tốt: có lịch sử phiên bản, người khác báo lỗi được. Nhưng tài khoản có thể bị xoá, kho có thể đổi tên. Vì vậy, khi gửi bài hãy tạo một bản lưu cố định:
- Kết nối kho GitHub với Zenodo, tạo một “release”, Zenodo sẽ tự lưu bản đó và cấp DOI.
- Hoặc tải trực tiếp file nén lên Zenodo, OSF hay kho của trường.
- Trong bài, trích dẫn DOI của bản lưu cố định, không chỉ đường link GitHub.
Lý do: phản biện và độc giả cần thấy đúng phiên bản mã đã tạo ra kết quả trong bài, không phải phiên bản bạn tiếp tục sửa sau đó.
Để mã và phần mềm được trích dẫn
Thêm file CITATION.cff vào kho: GitHub sẽ hiện nút “Cite this repository”. Trong bài, trích dẫn cả các gói phần mềm quan trọng bạn dùng; nhiều gói R và Python có sẵn câu trích dẫn (trong R, gõ citation(“tên gói”)). Người viết công cụ bạn dựa vào xứng đáng được ghi nhận như tác giả một bài báo.
Viết câu “Code availability”
- “Mã phân tích tái tạo mọi kết quả trong bài được lưu tại Zenodo (DOI: …) theo giấy phép MIT.”
- Khi dữ liệu hạn chế: “Mã phân tích có tại … Do hạn chế về đạo đức, dữ liệu gốc không công khai; kho mã kèm dữ liệu mô phỏng có cùng cấu trúc để chạy thử.”
Phương án dữ liệu mô phỏng đáng dùng hơn nhiều người nghĩ: người kiểm chứng xác nhận được mã làm đúng những gì bài viết mô tả, dù không thấy dữ liệu thật.
Kế hoạch một buổi chiều
- 30 phút: tạo bản sao sạch, gỡ thông tin nhạy cảm, đổi đường dẫn tuyệt đối thành tương đối.
- 60 phút: chạy lại từ đầu, sửa chỗ hỏng, ghi phiên bản gói.
- 30 phút: viết README theo sáu mục ở trên, thêm LICENSE và CITATION.cff.
- 30 phút: đưa lên kho, tạo bản lưu cố định có DOI, chèn DOI vào bản thảo.
Việc nên làm tiếp: chọn bài báo gần nhất của bạn có phần phân tích, và làm đúng bốn bước trên cho nó. Lần sau, bạn sẽ giữ cấu trúc này ngay từ ngày đầu dự án và gần như không tốn thêm thời gian nào.
Câu hỏi thường gặp
Mã của tôi lộn xộn, có nên công bố không?
Nên. Người đọc cần mã chạy được và lần theo được, không cần mã đẹp. Một README rõ và ánh xạ file nào tạo bảng nào đã giúp rất nhiều.
Nên dùng giấy phép nào cho mã nghiên cứu?
MIT là lựa chọn phổ biến cho mã phân tích vì đơn giản và cho phép dùng lại rộng. GPL phù hợp khi bạn muốn mọi bản cải tiến tiếp tục mở. Kiểm tra quy định của trường trước khi chọn.
Có cần DOI cho mã không, khi đã có link GitHub?
Nên có. DOI trỏ tới một bản lưu cố định, đúng phiên bản đã tạo ra kết quả trong bài, và không mất đi nếu kho GitHub bị đổi tên hay xoá.
Lỡ đẩy khoá API lên GitHub thì làm gì?
Thu hồi và đổi khoá ngay, vì xoá file không xoá được lịch sử phiên bản. Sau đó chuyển khoá sang biến môi trường hoặc file cấu hình không đưa lên kho.
Dữ liệu không chia sẻ được thì chia sẻ mã có ích gì?
Có. Kèm dữ liệu mô phỏng cùng cấu trúc, người khác vẫn kiểm tra được mã làm đúng như mô tả trong bài và dùng lại được cho dữ liệu của họ.
