Mercurial > audlegacy
annotate doc/HACKING @ 4779:aa79a84627b9
g_basename is deprecated, replace with g_path_get_basename.
author | Tony Vroon <chainsaw@gentoo.org> |
---|---|
date | Fri, 26 Sep 2008 21:02:49 +0100 |
parents | dde7262d0a35 |
children |
rev | line source |
---|---|
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
1 Hacking / coding guide for Audacious and Audacious-plugins |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
2 ========================================================== |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
3 (C) Copyright 2008 Audacious Development Team |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
4 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
5 |
4417 | 6 Preamble |
7 ======== | |
8 | |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
9 This document describes the guidelines for people who wish to work on |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
10 improving or cleaning up Audacious media player, or any of the plugins |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
11 we distribute in the plugins package. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
12 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
13 It is probably obvious to anyone who has taken a look into the depths |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
14 of Audacious source, that many of these guidelines are not actually |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
15 followed currently in all places, if at all. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
16 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
17 In fact, the purpose of this document is to act as a target to aim at, |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
18 when noticing and cleaning up uncompliant code.. or writing new code. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
19 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
20 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
21 Coding guidelines |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
22 ================= |
4534
8e8a82c9311a
Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents:
4420
diff
changeset
|
23 - Public functions in Audacious core SHOULD be documented via Doxygen |
8e8a82c9311a
Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents:
4420
diff
changeset
|
24 comments! In this case "public" means any functions that span modules |
8e8a82c9311a
Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents:
4420
diff
changeset
|
25 OR are available to plugins. |
8e8a82c9311a
Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents:
4420
diff
changeset
|
26 |
8e8a82c9311a
Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents:
4420
diff
changeset
|
27 Of course, most functions currently lack documentation. If you have |
8e8a82c9311a
Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents:
4420
diff
changeset
|
28 spare time, improve the situation. |
8e8a82c9311a
Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents:
4420
diff
changeset
|
29 |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
30 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
31 - We use Glib for portability. This means that we have sized integer types |
4419
35444232ac7e
Note about code duplication.
Matti Hamalainen <ccr@tnsp.org>
parents:
4416
diff
changeset
|
32 such as gint{16,32,64}, etc. and shorthand types like guint and guchar |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
33 provided, so please do use them. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
34 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
35 Arguably C99 provides inttypes.h with similar types, but C99 support |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
36 may not be complete on all platforms, it is both safer and more uniform |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
37 to use glib types. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
38 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
39 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
40 - Use other glib functionality, especially string handling like: |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
41 * g_snprintf(), g_strdup_printf(), g_strdup() ... |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
42 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
43 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
44 - However, avoid following Glib things: |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
45 * GString - Useless in most cases compared to normal 'C' string functions |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
46 and introduces conversions back and forth. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
47 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
48 * GList - GList is slow, either use GQueue or libmowgli lists. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
49 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
50 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
51 - Be sure to know when you are handling UTF-8 or something else! Glib offers |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
52 special g_ascii_*() functions for certain operations that you might need |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
53 when handling non-unicode strings. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
54 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
55 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
56 - When reading data from files, it's usually a BIG mistake to read structs |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
57 directly from the stream! This is not portable, as C does not guarantee |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
58 a struct not to have alignment padding (unless the struct is "packed", |
4549
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
59 but see below.) In effect sizeof(struct), unless packed, on some platform |
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
60 may not be equal to some other platform. |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
61 |
4549
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
62 Making struct "packed" via the C packed qualifier or "#pragma pack()" is |
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
63 a solution, but this must be used with care. Unaligned memory access |
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
64 causes performance penalties, and may cause other, more serious problems |
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
65 in some cases. For example, code written in assembler may not know about |
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
66 the un-alignment, and may thus fail with 'bus errors' on platforms that |
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
67 strictly required aligned data. |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
68 |
4549
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
69 The 100% safe way is to read individual members of the struct one by one |
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
70 from the stream. This may be bothersome, but by doing so, your code |
785b606fd504
Clarified and fixed the explanation of structure packing and unaligned memory access.
Matti Hamalainen <ccr@tnsp.org>
parents:
4534
diff
changeset
|
71 will be portable for sure. |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
72 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
73 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
74 - Always use Glib sized types for reading integer data from file streams. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
75 Using plain C types (like 'long int' for example) is not wise, because |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
76 they may be of different size on different platforms depending on the |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
77 platform ABI. For example, on some 64-bit platforms, 'long int' is |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
78 64 bits, while on 32-bit platforms it is 32 bits. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
79 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
80 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
81 - Audacious core provides some helper functions for reading endian-dependant |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
82 integers from VFS streams (aud_vfs_fget_{le,be}{16,32,64}), see vfs.h and |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
83 documentation for more information. |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
84 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
85 |
4419
35444232ac7e
Note about code duplication.
Matti Hamalainen <ccr@tnsp.org>
parents:
4416
diff
changeset
|
86 - Avoid reinventing wheels, avoid code duplication. If same thing is done |
35444232ac7e
Note about code duplication.
Matti Hamalainen <ccr@tnsp.org>
parents:
4416
diff
changeset
|
87 in two places, it should be in a library, or possibly in Audacious core. |
35444232ac7e
Note about code duplication.
Matti Hamalainen <ccr@tnsp.org>
parents:
4416
diff
changeset
|
88 Discuss about it with fellow developers. |
35444232ac7e
Note about code duplication.
Matti Hamalainen <ccr@tnsp.org>
parents:
4416
diff
changeset
|
89 |
35444232ac7e
Note about code duplication.
Matti Hamalainen <ccr@tnsp.org>
parents:
4416
diff
changeset
|
90 |
4741
10cfc41149ff
Apparently some people are dumber than I thought.
William Pitcock <nenolod@atheme.org>
parents:
4549
diff
changeset
|
91 - In the core, DO NOT WRITE CODE THAT IS DEPENDENT ON A SPECIFIC UI OR |
10cfc41149ff
Apparently some people are dumber than I thought.
William Pitcock <nenolod@atheme.org>
parents:
4549
diff
changeset
|
92 INTERFACE. The core should NEVER care what interface is in use. |
10cfc41149ff
Apparently some people are dumber than I thought.
William Pitcock <nenolod@atheme.org>
parents:
4549
diff
changeset
|
93 |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
94 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
95 Additional style guidelines |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
96 =========================== |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
97 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
98 - Indentation: Use the same indentation style (also spaces vs. tabs) |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
99 as the file you are editing. In new files/code, use indentation of |
4417 | 100 4 spaces (no tabs). When moving functions to new files, PLEASE |
101 reindent the code. | |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
102 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
103 - Whitespace usage in code: |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
104 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
105 a = 1; |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
106 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
107 if (b == d && !strcmp(a, c)) ... |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
108 |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
109 - Blocks: |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
110 |
4417 | 111 while (...) |
112 { | |
113 do_something(...); | |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
114 } |
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
115 |
4417 | 116 if (...) |
117 { | |
118 do_stuff(); | |
4415
2c3390afe10e
Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff
changeset
|
119 } |
4417 | 120 else |
121 { | |
122 do_other_stuff(); | |
123 } |