Bài giảng Kỹ thuật lập trình - Bài 9: Xây dựng tài liệu được biên soạn nhằm trang bị cho các bạn những kiến thức về các tài liệu trong và ngoài (internal và external), các quy tắc xây dựng tài liệu, quy ước viết mã nguồn và chú thích.
Bài XÂY DỰNG TÀI LIỆU Trịnh Thành Trung trungtt@soict.hust.edu.vn XÂY DỰNG TÀI LIỆU Các tài liệu (internal external) Các quy tắc xây dựng tài liệu Quy ước viết mã nguồn thích - CÁC LOẠI TÀI LIỆU CHƯƠNG TRÌNH - Các loại tài liệu chương trình • Tài liệu (Internal documentation) – Các thích cho mã nguồn (comments) • Tài liệu (External documentation) – Dành cho lập trình viên khác làm việc với mã nguồn • Tài liệu dành cho người sử dụng – Cẩm nang dành cho người sử dụng mã nguồn • Các loại tài liệu khác – Tài liệu kiểm thử… TÀI LIỆU TRONG - Chú thích hợp lý • Các thích có giúp người đọc hiểu mã nguồn hay khơng ? • Các thích có thực bổ ích hay khơng? Lập trình viên viết thích thích thực cần thiết để hiểu mã nguồn hay viết có ? • Người đọc dàng làm việc với mã nguồn có thích hay khơng? • Nếu khơng thích nên đặt tham chiếu đến tài liệu cho phép người đọc hiểu vấn đề sâu Các cách thích cần tránh: Chú thích vơ nghĩa • Làm chủ ngơn ngữ –Hãy để chương trình tự diễn tả thân –Rồi… • Viết thích để thêm thơng tin i= i+1; /* Add one to i */ for (i= 0; i < 1000; i++) { /* Tricky bit */ … } int x,y,q3,z4; /* Define some variables */ int main() /* Main routine */ while (i < 7) { /*This comment carries on and on */ Các thích cần tránh: Chú thích nhằm mục đích phân đoạn mã nguồn while (j < ARRAYLEN) { printf ("J is %d\n", j); for (i= 0; i < MAXLEN; i++) { /* These comments only */ for (k= 0; k < KPOS; k++) { /* Serve to break up */ printf ("%d %d\n",i,k); /* the program */ } /* And make the indentation */ } /* Very hard for the programmer to see */ j++; } Viết thích đủ ? • Chú thích tốt, điều khơng có nghĩa dịng lệnh cần viết thích • Chú thích đoạn (“paragraphs”) code, đừng thích dịng – vd., “Sort array in ascending order” • Chú thích liệu tổng thể – Global variables, structure type definitions, … • Nhiều thích q làm cho mã nguồn trở nên khó đọc Viết thích đủ? • Ít thích q làm mã nguồn trở nên khó hiểu • Chỉ viết thích vịng phút bạn khơng thể hiểu đoạn lệnh làm gì, • Viết thích tương ứng với code – Thay đổi code thay đổi Function Comments • Mơ tả cần thiết để gọi hàm cách xác – Mơ tả hàm làm gì, khơng phải làm – Bản thân Code phải rõ ràng, dễ hiểu để biết cách làm việc… – Nếu khơng, viết thích bên định nghĩa hàm • Mô tả đầu vào: Tham số truyền vào, đọc file gì, biến tổng thể dùng • Mơ tả outputs: Giá trị trả về, tham số truyền ra, ghi file gì, biến tổng thể mà tác động tới Ví dụ • Bad /* decomment.c */ int main(void) { /* Đọc ký tự Dựa ký tự trạng thái DFA thời, gọi hàm xử lý trạng thái tương ứng Lặp hết tệp end-of-file */ … } –Giải thích hàm làm Ví dụ • Good /* decomment.c */ int main(void) { /* Đọc chương trình C qua stdin Ghi stdout với thích thay dấu cách Trả thành công, EXIT_FAILURE khơng thành cơng */ … } –Giải thích hàm làm Các quy tắc viết thích khác • Chú thích bạn cố tình thực thao tác kỳ cục khiến LTV khác khó hiểu • Nếu thích dài, tốt nên đặt tham chiếu sang đoạn văn mô tả chi tiết chỗ khác • Đừng cố gắng định dạng thích theo cách gây nhầm lẫn với mã nguồn (ví dụ, đặt gióng hàng riêng cho thích) TÀI LIỆU NGỒI - Tài liệu ngồi • Giới thiệu với LTV khác mã nguồn dùng để làm • Nhiều công ty lớn tự đặt chuẩn riêng để viết tài liệu ngồi • Mục tiêu cho phép LTV khác sử dụng thay đổi mã nguồn mà khơng cần đọc hiểu dịng lệnh Viết tài liệu ngồi: Bước • Miêu tả cách tổng quát cách thức hoạt động chương trình – Chương trình phải làm gì? – Phải đọc từ nguồn liệu nào, ghi vào đâu? – Giả thiết với đầu vào? – Dùng giải thuật nào? Viết tài liệu ngồi: Bước • Miêu tả cách tổng quát quy trình nghiệp vụ chương trình (giống cách miêu tả flowchart) • Có thể vẽ biểu đồ • Giải thích giải thuật phức tạp sử dụng chương trình, cho biết tìm lời giải thích đâu Viết tài liệu ngồi: Bước • Nếu chương trình bao gồm nhiều file, giải thích nội dung file • Giải thích cấu trúc liệu sử dụng phổ biến chương trình • Giải thích việc sử dụng biến tồn cục chương trình Viết tài liệu ngồi: Bước • Miêu tả hàm chương trình – LTV tự định hàm hàm chương trình – Xem xét hàm hàm nghiệp vụ thực sự, không thiết phải hàm dài hay khó viết • Miêu tả tham số đầu vào giá trị trả Các cơng cụ sinh tài liệu • Doxygen – Hỗ trợ nhiều ngơn ngữ lập trình (C/C++, C#, Java, PHP, Python…) – Chạy Linux, Windows, MacOS Các cơng cụ sinh tài liệu • Javadoc – Có sẵn JavaSDK – Một số IDE tự động sinh tài liệu javadoc TÀI LIỆU NGƯỜI DÙNG VÀ TÀI LIỆU KIỂM THỬ - Viết tài liệu cho người dùng • Đây hướng dẫn sử dụng (user manual) • Là phần thiếu viết tài liệu cho dự án phần mềm, phần quan trọng Viết tài liệu kiểm thử • Tài liệu kiểm thử số tài liệu quan dự án phần mềm • Nếu được, bạn nên viết số chứng việc bạn kiểm thử chương trình bạn với nhiều đầu vào khác • Việc khơng viết tài liệu kiểm thử gây nhiều hậu nặng nề ...XÂY DỰNG TÀI LIỆU Các tài liệu (internal external) Các quy tắc xây dựng tài liệu Quy ước viết mã nguồn thích - CÁC LOẠI TÀI LIỆU CHƯƠNG TRÌNH - Các loại tài liệu chương trình • Tài liệu. .. IDE tự động sinh tài liệu javadoc TÀI LIỆU NGƯỜI DÙNG VÀ TÀI LIỆU KIỂM THỬ - Viết tài liệu cho người dùng • Đây hướng dẫn sử dụng (user manual) • Là phần khơng thể thiếu viết tài liệu cho dự án... Viết tài liệu kiểm thử • Tài liệu kiểm thử số tài liệu quan dự án phần mềm • Nếu được, bạn nên viết số chứng việc bạn kiểm thử chương trình bạn với nhiều đầu vào khác • Việc khơng viết tài liệu