Bài 19.726 phút đọc

Header guard và cách viết header

Sau bài này bạn sẽ làm được

Giải thích lỗi định nghĩa trùng khi thiếu header guard
Đặt tên guard theo quy ước tránh trùng trong dự án lớn
So sánh include guard với pragma once
Liệt kê thứ được phép và thứ bị cấm trong một tệp header

Ba dòng ở đầu và cuối mỗi tệp header trông như nghi thức thừa. Chúng không thừa: không có chúng thì một dự án chỉ cần ba tệp là đã không biên dịch được nữa.

#Vì sao include hai lần là lỗi

Chỉ cần một header include header khác là cùng một tệp tới nơi theo hai đường.

Ba tệp là đủ để hỏng

/* a.h */
struct S { int x; };

/* b.h */
#include "a.h"

/* m.c */
#include "a.h"
#include "b.h"

int main(void) { struct S s = { 1 }; return s.x - 1; }

terminal

gcc -std=c11 -o m m.c

In file included from b.h:1,
                 from m.c:2:
a.h:1:8: error: redefinition of 'struct S'
 struct S { int x; };
        ^
In file included from m.c:1:
a.h:1:8: note: originally defined here

Nội dung tệp bị dán vào hai lần

/* m.c sau khi tien xu ly, khong co guard: */

struct S { int x; };      /* tu #include "a.h" */
struct S { int x; };      /* tu #include "b.h" -> a.h */

int main(void) { struct S s = { 1 }; return s.x - 1; }

/* Dinh nghia struct hai lan la loi, ke ca khi hai lan giong het.
   C khong cho phep dinh nghia lai mot kieu trong cung pham vi. */

Không phải thứ gì lặp lại cũng là lỗi

Xuất hiện hai lần	Có lỗi không	Vì sao
Định nghĩa struct hoặc union	Có	Định nghĩa kiểu chỉ được một lần
typedef giống hệt	Không từ C11	C11 cho phép lặp lại typedef giống hệt
enum	Có	Như struct
Nguyên mẫu hàm giống hệt	Không	Khai báo lặp lại bao nhiêu lần cũng được
extern khai báo biến	Không	Cũng chỉ là khai báo
#define giống hệt từng token	Không	Xem Bài 19.2
#define khác nhau	Cảnh báo	Định nghĩa sau thắng
Định nghĩa hàm	Có	Vi phạm quy tắc một định nghĩa, Bài 20.2

Nói cách khác, một header chỉ có nguyên mẫu hàm và #define có thể sống sót qua nhiều lần include. Nhưng gần như mọi header thật đều có ít nhất một struct hoặc enum, nên quy tắc thực dụng là mọi header đều có guard, không có ngoại lệ.

#Ba dòng bao quanh mọi header

sinhvien.h

#ifndef SINHVIEN_H
#define SINHVIEN_H

/* ... toan bo noi dung header ... */

#endif /* SINHVIEN_H */

Header guard

Ba chỉ thị bao quanh toàn bộ nội dung một header. Lần include đầu tiên, macro chưa tồn tại nên nội dung được xử lý và macro được định nghĩa. Mọi lần sau, macro đã có nên preprocessor bỏ qua toàn bộ khối.

terminal

# Cùng ba tệp như trên, chỉ thêm guard vào a.h

gcc -std=c11 -o m2 m2.c && echo 'bien dich sach'

bien dich sach

/* Dien bien lan mot: */
#ifndef SINHVIEN_H       -> SINHVIEN_H chua co   -> vao trong
#define SINHVIEN_H       -> gio no co roi
   ... noi dung duoc xu ly ...
#endif

/* Dien bien lan hai: */
#ifndef SINHVIEN_H       -> SINHVIEN_H DA CO     -> bo qua het
   ... preprocessor nuot toan bo, khong sinh mot token nao ...
#endif

Ba lỗi thường gặp khi viết guard

Quên endif

#ifndef SINHVIEN_H
#define SINHVIEN_H
struct SinhVien { ... };
/* QUEN #endif */

Có endif, kèm chú thích

#ifndef SINHVIEN_H
#define SINHVIEN_H
struct SinhVien { ... };
#endif /* SINHVIEN_H */

/* Loi 2: hai header dung chung mot ten guard */

/* sinhvien.h */          /* sanpham.h */
#ifndef SV_H              #ifndef SV_H          <- TRUNG
#define SV_H              #define SV_H
...                       ...
#endif                    #endif

/* Tep include sau se bi bo qua HOAN TOAN.
   Trieu chung: mot kieu bao khong khai bao, du ban da include
   dung tep. Rat kho doan ra. */

/* Loi 3: co gi do nam NGOAI guard */

#include <stdio.h>        <- ngoai guard: bi xu ly moi lan include
#ifndef SINHVIEN_H
#define SINHVIEN_H
...
#endif

/* Khong sai ve ket qua, nhung stdio.h bi mo lai moi lan,
   va bo dem cua chinh no moi giup. Dat MOI THU trong guard. */

Chú thích sau endif giúp khi header dài

#endif /* SINHVIEN_H */

/* Voi header ba tram dong co nhieu khoi #ifdef ben trong,
   dong #endif cuoi cung rat de bi lan voi cac #endif khac.
   Chu thich noi ro no dong cai nao. */

#Đặt tên guard

Quy mô dự án	Kiểu tên	Ví dụ
Bài tập, một thư mục	TENTEP_H	SINHVIEN_H
Dự án có thư mục con	DUONGDAN_TENTEP_H	QUANLY_LUUTRU_CSV_H
Thư viện phát hành cho người khác	TENDUAN_DUONGDAN_TENTEP_H	SVLIB_CORE_STUDENT_H

Ba kiểu tên nên tránh

#ifndef _SINHVIEN_H      /* bat dau bang gach duoi: danh cho thu vien,
                            xem Bai 19.2 */

#ifndef __SINHVIEN_H__   /* hai gach duoi: cung danh cho thu vien */

#ifndef HEADER           /* qua chung chung: chac chan trung */

#ifndef SINHVIEN_H       /* dung */

Có công cụ sinh guard tự động

/* Nhieu trinh soan thao co lenh "them header guard".
   Neu khong co, mot dong shell la du: */

tao_guard() {
    ten=$(basename "$1" | tr 'a-z.-' 'A-Z__')
    printf '#ifndef %s\n#define %s\n\n\n\n#endif /* %s */\n' \
           "$ten" "$ten" "$ten" > "$1"
}

tao_guard include/luutru.h
/* -> #ifndef LUUTRU_H
      #define LUUTRU_H
      ...
      #endif  */

#pragma once

#pragma once

/* ... noi dung header ... */

/* Khong can #endif. */

Tiêu chí	Include guard	pragma once
Trong chuẩn C	Có	Không
Chạy trên mọi trình biên dịch	Có	Gần như, nhưng không đảm bảo
Số dòng phải viết	3	1
Trùng tên gây lỗi im lặng	Có	Không
Cùng tệp qua hai đường dẫn khác nhau	Nhận ra đúng	Có thể không nhận ra
Dùng được cho việc include cố ý nhiều lần	Có, bằng cách bỏ guard	Không

Chỗ pragma once thua: cùng tệp, hai đường

/* Neu du an co mot lien ket tuong trung, hoac mot tep
   duoc tro toi qua hai duong dan khac nhau: */

#include "include/sinhvien.h"
#include "../du-an/include/sinhvien.h"

/* pragma once nhan dien tep bang thiet bi va so inode,
   hoac bang duong dan da chuan hoa, tuy cai dat.
   Voi lien ket cung hoac he tep mang thi no co the
   coi day la HAI tep khac nhau va dan noi dung hai lan.

   Include guard khong co van de nay: no chi nhin ten macro. */

Khóa học này dùng include guard

Lý do đơn giản: nó nằm trong chuẩn. #pragma once ngắn hơn và hầu như trình biên dịch nào cũng hỗ trợ, và nếu dự án của bạn chọn nó thì cũng không sao. Điều quan trọng là chọn một kiểu và dùng nhất quán, chứ không phải chọn cái nào.

/* Mot so du an dung CA HAI, de chac chan: */
#pragma once
#ifndef SINHVIEN_H
#define SINHVIEN_H
...
#endif

/* Khong sai, nhung theo tac gia thi day la lo lang thua.
   Chon mot cai. */

#Cách viết một header tốt

sinhvien.h, thứ tự chuẩn

#ifndef SINHVIEN_H
#define SINHVIEN_H

/* 1. Include nhung gi HEADER NAY can, khong hon */
#include <stddef.h>       /* size_t  */
#include <stdint.h>       /* uint16_t */

#include "loi.h"          /* MaLoi   */

/* 2. Hang so */
enum {
    SV_MSSV_CO = 16,
    SV_TEN_CO  = 64,
    SV_SO_MON  = 5,
};

/* 3. Kieu du lieu */
typedef struct {
    char     mssv[SV_MSSV_CO];
    char     ho_ten[SV_TEN_CO];
    uint16_t diem_x100[SV_SO_MON];
} SinhVien;

/* 4. Khai bao bien toan cuc, PHAI co extern, xem Bai 20.3 */
extern const char *const SV_TEN_XEP_LOAI[5];

/* 5. Nguyen mau ham cong khai */
MaLoi       sv_kiem_tat_ca(const SinhVien *sv);
uint16_t    sv_diem_tb_x100(const SinhVien *sv);
const char *sv_xep_loai(const SinhVien *sv);

/* 6. Ham nho, neu co, phai la static inline */
static inline int sv_dat(const SinhVien *sv) {
    return sv_diem_tb_x100(sv) >= 500;
}

#endif /* SINHVIEN_H */

Bốn thứ không bao giờ để trong header

Không được để	Vì sao	Đặt ở đâu thay thế
Định nghĩa biến, ví dụ int g_dem = 0;	Mỗi tệp include tạo một định nghĩa, lỗi multiple definition	Khai báo extern trong .h, định nghĩa trong đúng một .c
Định nghĩa hàm không static và không inline	Cùng lý do	Nguyên mẫu trong .h, thân trong .c
Macro tên chung chung, ví dụ #define max ...	Phá mọi mã include nó, xem Bài 19.2	Đặt tiền tố, hoặc dùng static inline
using-like macro đổi cú pháp C	Người sau không đọc nổi	Đừng viết

terminal

# Định nghĩa biến trong header, hai tệp .c include nó

gcc -std=c11 -o xa x1.c x2.c

x2.o:x2.c:(.data+0x0): multiple definition of `g_muc_log'
x1.o:x1.c:(.data+0x0): first defined here
collect2: error: ld returned 1 exit status

Header phải tự đủ: dịch được một mình

Dựa vào include của người dùng

/* sinhvien.h */
typedef struct { char ten[64]; size_t n; } SinhVien;
/* KHONG include <stddef.h>, nhung dung size_t */

/* Chay duoc neu nguoi dung tinh co include <stdio.h> TRUOC.
   Hong ngay khi ai do include sinhvien.h dau tien. */

Tự include những gì mình cần

/* sinhvien.h */
#include <stddef.h>       /* size_t */

typedef struct { char ten[64]; size_t n; } SinhVien;

terminal

# Cách kiểm tra: dịch mỗi header một mình

for h in include/*.h; do echo "#include \"$h\"" > /tmp/t.c; gcc -Iinclude -fsyntax-only /tmp/t.c || echo "KHONG TU DU: $h"; done

/tmp/t.c:1:  error: unknown type name 'size_t'
KHONG TU DU: include/sinhvien.h

Vòng lặp này đáng chạy trong quy trình build. Nó bắt được lớp lỗi mà người dùng thư viện của bạn sẽ gặp, còn bạn thì không, chỉ vì thứ tự include trong dự án bạn tình cờ đúng.

Nhưng cũng đừng include thừa

/* sinhvien.h */
#include <stdio.h>        /* CHI de khai bao mot ham nhan FILE* */
#include <stdlib.h>       /* KHONG dung toi gi ca */
#include <string.h>       /* KHONG dung toi gi ca */

/* Moi include thua o day duoc dan vao MOI tep .c include
   sinhvien.h. Voi ba muoi tep .c thi do la ba muoi lan
   phan tich stdlib.h va string.h vo ich.

   Quy tac: header chi include thu no THAT SU can trong
   chinh no. Nhung thu chi ham CAI DAT can thi include
   trong tep .c. Bai 20.5 se noi ky hon. */

Danh sách kiểm cho mỗi header

Câu hỏi	Cách kiểm
Có header guard không	grep '^#ifndef' tệp.h
Tên guard có trùng tệp khác không	grep -rh '^#ifndef' \| sort \| uniq -d
Mọi thứ có nằm trong guard không	Nhìn dòng đầu và dòng cuối
Dịch được một mình không	Tạo tệp .c chỉ include nó rồi gcc -fsyntax-only
Có định nghĩa biến hoặc hàm nào không	grep -n '^[a-zA-Z].*=' và grep -n '^{'
Có include nào thừa không	Bỏ từng cái rồi build lại, xem Bài 20.5

Tự làm thử

Tạo ba tệp a.h, b.h, m.c không có guard và đọc thông báo lỗi.
Thêm guard vào a.h và xác nhận nó biên dịch sạch.
Cố ý đặt cùng tên guard cho hai header khác nhau, include cả hai, và xem triệu chứng.
Viết vòng lặp shell kiểm tra mọi header trong dự án có dịch được một mình không.
Đặt int g_dem = 0; trong một header rồi include nó từ hai tệp .c, đọc lỗi của trình liên kết.
Bỏ một dòng #include khỏi header của bạn và xem có tệp nào hỏng không.

Trình chấm điểm tự động sẽ được bổ sung ở giai đoạn sau. Hiện tại bạn tự chạy thử trên máy.

Tóm tắt

Không có guard, chỉ cần một header include header khác là đã có định nghĩa struct hai lần.
Guard gồm ba dòng, và toàn bộ nội dung header phải nằm trong chúng, kể cả các dòng #include.
Tên guard phải duy nhất trong dự án và không được bắt đầu bằng gạch dưới. Trùng tên gây lỗi im lặng rất khó tìm.
#pragma once ngắn hơn nhưng không nằm trong chuẩn. Chọn một kiểu và dùng nhất quán.
Header phải tự đủ: include những gì chính nó cần, và không include thứ chỉ tệp .c cần.
Không bao giờ định nghĩa biến hay hàm không static trong header.