Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/docs/reference/c/coding-style.md @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 # Coding Style
2
3 This is a basic overview of the MuPDF coding style used in the C library.
4
5 ## Indentation
6
7 There are two hard rules:
8
9 1. Indent with hard tabs.
10 2. Do not vertically align anything beyond the left edge!
11
12 If you want a different indentation level, configure your editor to use
13 whichever tab width you prefer. If you follow the two rules above, everything
14 will work out perfectly.
15
16 The rest you should be able to infer from the source around you:
17
18 - Curly braces on their own line.
19 - Put a space between `if`, `for`, `while`, and their expression.
20
21 ## Names
22
23 Functions should be named according to one of the following schemes:
24
25 - verb_noun
26 - verb_noun_with_noun
27 - noun_attribute
28 - set_noun_attribute
29 - noun_from_noun -- convert from one type to another (avoid noun_to_noun)
30
31 Prefixes are mandatory for exported functions, macros, enums, globals and
32 types.
33
34 - fz for common code
35 - pdf, xps, etc., for interpreter specific code
36
37 Prefixes are optional (but encouraged) for private functions and types.
38
39 Avoid using 'get' as this is a meaningless and redundant filler word.
40
41 These words are reserved for reference counting schemes:
42
43 - new, create, find, load, open, keep -- return objects that you are responsible for freeing.
44 - drop -- relinquish ownership of the object passed in.
45
46 When searching for an object or value, the name used depends on whether
47 returning the value is passing ownership:
48
49 - lookup -- return a value or borrowed pointer
50 - find -- return an object that the caller is responsible for freeing
51
52 ## Types
53
54 Various different integer types are used throughout MuPDF.
55
56 In general:
57
58 - int is assumed to be 32bit at least.
59 - short is assumed to be exactly 16 bits.
60 - char is assumed to be exactly 8 bits.
61 - array sizes, string lengths, and allocations are measured using size_t.
62 - size_t is 32bit in 32bit builds, and 64bit on all 64bit builds.
63 - buffers of data use unsigned chars (or uint8_t).
64 - Offsets within files/streams are represented using int64_t.
65
66 In addition, we use floats (and avoid doubles when possible), assumed to be
67 IEEE compliant.
68
69 ## Reference counting
70
71 Reference counting uses special words in functions to make it easy to remember
72 and follow the rules.
73
74 Words that take ownership: new, find, load, open, keep.
75
76 Words that release ownership: drop.
77
78 If an object is returned by a function with one of the special words that take
79 ownership, you are responsible for freeing it by calling "drop" or "free", or
80 "close" before you return. You may pass ownership of an owned object by return
81 it only if you name the function using one of the special words.
82
83 Any objects returned by functions that do not have any of these special words,
84 are borrowed and have a limited life time. Do not hold on to them past the
85 duration of the current function, or stow them away inside structs. If you need
86 to keep the object for longer than that, you have to either "keep" it or make
87 your own copy.