Thân luận văn chỉ nên chứa những đoạn mã ngắn minh hoạ đúng ý chính đang giải thích, thường vài chục dòng trở xuống, có đánh số và chú thích. Mã đầy đủ để ở kho mã có ghi phiên bản hoặc phụ lục. Khi cần giải thích thuật toán, giả mã thường rõ hơn mã thật.
Nhiều bản thảo luận văn công nghệ thông tin có hàng chục trang mã dán liền nhau, phông chữ lộn xộn, không ai đọc. Người chấm không cần đọc từng dòng mã để biết bạn lập trình được; họ cần thấy bạn hiểu điều mình viết và biết chọn phần đáng trình bày. Cách trình bày mã nói lên điều đó khá rõ.
Đoạn mã nào vào đâu?
Quyết định theo câu hỏi: người đọc có cần đoạn này để hiểu lập luận ở trang đó không?
| Loại mã | Vị trí | Hình thức |
|---|---|---|
| Thuật toán cốt lõi của đề tài | Thân bài, chương phương pháp hoặc thiết kế | Giả mã, có thể kèm đoạn mã thật ngắn |
| Xử lý đặc biệt, điểm khó của cài đặt | Thân bài, chương cài đặt | Đoạn mã ngắn, lược bớt phần không liên quan |
| Cấu hình, tệp thiết lập môi trường | Phụ lục hoặc kho mã | Trích phần chính, mô tả bằng lời |
| Mã giao diện, mã lặp lại kiểu thêm sửa xoá | Kho mã | Không đưa vào văn bản |
| Toàn bộ mã nguồn | Kho mã có phiên bản, hoặc đĩa, tệp nộp kèm theo quy định | Ghi đường dẫn và phiên bản trong phụ lục |
Viết giả mã cho dễ đọc
Khi nào dùng giả mã?
Khi bạn trình bày thuật toán, quy trình xử lý, hoặc logic không phụ thuộc ngôn ngữ lập trình. Giả mã giúp hội đồng có người không dùng ngôn ngữ của bạn vẫn đọc được, và buộc bạn bỏ những chi tiết kỹ thuật không cần.
Quy ước nên giữ
Đặt tên thuật toán, ghi rõ đầu vào và đầu ra ở đầu, đánh số dòng, dùng từ khoá nhất quán như for, if, return hoặc bản tiếng Việt tương đương nhưng không trộn lẫn. Mỗi bước gọi hàm phức tạp có thể thay bằng một câu mô tả. Nếu bạn soạn bằng LaTeX, các gói như algorithm2e hay algorithmicx hỗ trợ trình bày; trong Word thì dùng bảng một cột có đánh số dòng.
Giải thích ngay sau giả mã
Mỗi khối giả mã cần một đoạn văn giải thích các dòng then chốt, độ phức tạp nếu liên quan, và điểm khác với thuật toán gốc nếu bạn cải tiến. Giả mã không có lời giải thích thì người đọc vẫn phải tự đoán.
Một cách kiểm tra đơn giản: đưa khối giả mã cho một bạn cùng lớp không làm đề tài này, nhờ bạn kể lại thuật toán bằng lời. Chỗ bạn ấy kể sai thường là chỗ giả mã đang mơ hồ hoặc thiếu một bước, và đó cũng là chỗ hội đồng dễ hỏi nhất.
Định dạng đoạn mã thật
Phông và khung
Dùng phông chữ đơn cách cho mã, cỡ nhỏ hơn văn bản một chút nhưng vẫn đọc được khi in. Đặt trong khung hoặc nền nhạt để tách khỏi văn bản. Không chụp ảnh màn hình trình soạn thảo để dán vào: ảnh mờ khi in, không tìm kiếm được và không chép lại được để kiểm tra.
Đánh số và chú thích
Đánh số đoạn mã giống như bảng và hình, ví dụ “Đoạn mã 4.2”, kèm chú thích nói đoạn mã làm gì. Trong văn bản, nhắc tới đoạn mã bằng số. Nếu trường bạn chưa quy định cách đánh số đoạn mã, hỏi người hướng dẫn và giữ nhất quán.
Đặt tên biến cho người đọc
Đoạn mã trích vào luận văn là để người khác đọc, nên tên biến, tên hàm cần nói lên ý nghĩa. Nếu mã gốc dùng tên viết tắt khó hiểu, có thể đổi tên trong đoạn trích cho dễ đọc, miễn là ghi chú rằng đoạn trích đã được chỉnh để trình bày và logic không đổi.
Lược bớt có đánh dấu
Bỏ phần nhập thư viện, xử lý lỗi thường quy, ghi nhật ký nếu không liên quan. Đánh dấu chỗ lược bằng một dòng chú thích như # ... bỏ phần kiểm tra đầu vào để người đọc biết đây là trích đoạn, không phải toàn bộ hàm.
Đưa đoạn mã vào Word cho gọn
Nếu luận văn soạn bằng Word, các bước sau giúp đoạn mã đồng đều trong toàn văn bản.
- Tạo một kiểu đoạn (style) riêng cho mã: phông đơn cách, cỡ chữ cố định, giãn dòng đơn, nền nhạt hoặc viền mảnh.
- Dán mã ở dạng văn bản thuần (
Keep Text Only) rồi áp kiểu đoạn vừa tạo, tránh mang theo định dạng của trình soạn mã. - Đặt đoạn mã trong bảng một ô nếu muốn khung không bị tách khi sang trang, hoặc bật tuỳ chọn giữ các dòng cùng trang.
- Chèn chú thích bằng tính năng
Insert Captionvới nhãn riêng cho đoạn mã để đánh số tự động và lập được danh mục. - Kiểm tra bản in thử một trang để chắc cỡ chữ đọc được và thụt lề không bị mất.
Với LaTeX, gói listings hoặc minted làm những việc này tự động, kể cả đánh số dòng và chú thích.
Mã không phải của bạn: trích đoạn cũng phải ghi nguồn
Nếu đoạn mã bạn đưa vào luận văn lấy từ tài liệu hướng dẫn, diễn đàn hỏi đáp, kho mã mở, hay do công cụ AI gợi ý rồi bạn chỉnh sửa, hãy ghi nguồn ngay trong chú thích của đoạn mã và nói rõ phần nào bạn thay đổi. Việc ghi nhận đầy đủ thư viện và mã mở trong toàn bộ dự án là một chủ đề riêng, nhưng ở mức trình bày thì nguyên tắc đơn giản: người đọc không được phải đoán đoạn mã nào là của ai.
Kho mã: đặt sao cho hội đồng kiểm tra được
Ghi phiên bản cụ thể. Trong phụ lục, ghi tên kho mã và mã phiên bản (ví dụ thẻ phát hành hoặc mã commit) ứng với bản luận văn nộp. Mã có thể tiếp tục thay đổi sau đó, nhưng hội đồng cần xem đúng phiên bản bạn mô tả.
Có tệp hướng dẫn chạy. Một tệp README nêu yêu cầu môi trường, cách cài, cách chạy thực nghiệm hoặc khởi động hệ thống, dữ liệu mẫu để thử.
Tách bí mật khỏi mã. Khoá API, mật khẩu cơ sở dữ liệu, dữ liệu cá nhân của người dùng thử không được đẩy lên kho mã. Dùng tệp cấu hình mẫu và hướng dẫn tự điền.
Theo quy định nộp lưu. Một số trường yêu cầu nộp mã trên thiết bị lưu trữ hoặc hệ thống nội bộ thay vì đường dẫn công khai. Làm theo quy định của trường bạn.
Tình huống: từ ba mươi trang mã xuống bốn đoạn
Bản đầu. Một sinh viên làm ứng dụng quản lý kho cho cửa hàng vật liệu xây dựng dán ba mươi trang mã các lớp điều khiển vào chương cài đặt.
Câu hỏi của người hướng dẫn. Trong ba mươi trang đó, đâu là chỗ em tự hào nhất? Sinh viên chỉ ra hàm tính tồn kho khi có hàng chuyển giữa hai kho chưa nhận và hàm quy đổi đơn vị bao, tấn, khối.
Bản sửa. Chương cài đặt còn bốn đoạn mã ngắn kèm giả mã cho thuật toán quy đổi, giải thích các trường hợp biên. Toàn bộ mã ở kho có thẻ phiên bản, phụ lục ghi đường dẫn và hướng dẫn chạy.
Lỗi hay gặp khi trình bày mã
Rà bản thảo theo danh sách sau.
- Ảnh chụp màn hình mã thay cho văn bản mã.
- Đoạn mã không đánh số, không chú thích, không được nhắc tới trong văn bản.
- Dán nguyên hàm dài, phần lớn là mã giao diện.
- Giả mã trộn cú pháp nhiều ngôn ngữ.
- Kho mã không có hướng dẫn chạy hoặc không khớp phiên bản luận văn.
- Lộ khoá truy cập, mật khẩu trong đoạn mã trích.
Câu hỏi thường gặp
Mã nguồn có tính vào số trang của luận văn không?
Tuỳ quy định của trường bạn. Nhiều trường không tính phụ lục vào số trang tối thiểu của phần chính, nên mã dài càng nên để phụ lục hoặc kho mã.
Có bắt buộc đưa mã nguồn lên GitHub không?
Không bắt buộc ở mọi trường. Kho mã công khai tiện cho hội đồng kiểm tra, nhưng nếu dự án làm cho doanh nghiệp hoặc có dữ liệu nhạy cảm thì theo hình thức nộp lưu của trường.
Giả mã nên viết tiếng Việt hay tiếng Anh?
Cả hai đều được, miễn nhất quán trong toàn luận văn. Từ khoá điều khiển thường giữ tiếng Anh, phần mô tả bước có thể viết tiếng Việt.
Đoạn mã trong luận văn có bị phần mềm kiểm trùng đánh dấu không?
Có thể, vì mã mẫu phổ biến xuất hiện ở nhiều nơi. Mã tự viết thì giải thích được; mã dùng lại thì ghi nguồn rõ ràng.
Có nên tô màu cú pháp cho đoạn mã khi in?
Có thể, nhưng chọn màu vẫn đọc được khi in đen trắng. Nhiều người chọn nền nhạt và chữ đen để an toàn.
Đoạn mã bao nhiêu dòng là quá dài cho thân bài?
Không có con số cố định. Nếu đoạn mã dài hơn nửa trang, hãy cân nhắc lược bớt, tách nhỏ hoặc chuyển sang giả mã kèm trích dẫn vị trí trong kho mã.