annotate HACKING @ 4537:9fb29ee322d3

Added a note about problems with certain URIs.
author Matti Hamalainen <ccr@tnsp.org>
date Sat, 10 May 2008 22:45:04 +0300
parents 8e8a82c9311a
children 785b606fd504
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
4417
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
4 Written by Matti 'ccr' Hämäläinen <ccr@tnsp.org>, and mercilessly
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
5 edited by others.
4415
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
6
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
7
4417
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
8 Preamble
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
9 ========
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
10
4415
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
11 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
12 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
13 we distribute in the plugins package.
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
14
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
15 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
16 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
17 followed currently in all places, if at all.
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
18
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
19 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
20 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
21
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
22
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
23 Coding guidelines
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
24 =================
4534
8e8a82c9311a Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents: 4420
diff changeset
25 - 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
26 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
27 OR are available to plugins.
8e8a82c9311a Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents: 4420
diff changeset
28
8e8a82c9311a Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents: 4420
diff changeset
29 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
30 spare time, improve the situation.
8e8a82c9311a Add a note about Doxygen documentation.
Matti Hamalainen <ccr@tnsp.org>
parents: 4420
diff changeset
31
4415
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
32
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
33 - 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
34 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
35 provided, so please do use them.
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
36
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
37 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
38 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
39 to use glib types.
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
40
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
41
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
42 - Use other glib functionality, especially string handling like:
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
43 * g_snprintf(), g_strdup_printf(), g_strdup() ...
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
44
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
45
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
46 - However, avoid following Glib things:
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
47 * 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
48 and introduces conversions back and forth.
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 * GList - GList is slow, either use GQueue or libmowgli lists.
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
51
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
52
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
53 - 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
54 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
55 when handling non-unicode strings.
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
56
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
57
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
58 - 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
59 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
60 a struct not to have alignment padding (unless the struct is "packed",
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
61 but see below.) In effect sizeof(struct) on some platform may not be
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
62 equal to some other platform.
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
63
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
64 Some clever people might think that making struct "packed" via the
4416
ac8d871b6075 Oops, some text was missing.
Matti Hamalainen <ccr@tnsp.org>
parents: 4415
diff changeset
65 C packed qualifier would be a solution, but this will cause problems
ac8d871b6075 Oops, some text was missing.
Matti Hamalainen <ccr@tnsp.org>
parents: 4415
diff changeset
66 on platforms which require words to be aligned in memory - so it
ac8d871b6075 Oops, some text was missing.
Matti Hamalainen <ccr@tnsp.org>
parents: 4415
diff changeset
67 "works" on x86 (with performance penalty), but will fail with bus error
ac8d871b6075 Oops, some text was missing.
Matti Hamalainen <ccr@tnsp.org>
parents: 4415
diff changeset
68 on elsewhere.
4415
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
69
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
70 What you SHOULD do is read individual members of the struct one by one
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
71 from the stream. This may sound bothersome, but by doing so, your code
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
72 will be portable.
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
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
75 - 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
76 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
77 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
78 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
79 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
80
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
81
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
82 - Audacious core provides some helper functions for reading endian-dependant
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
83 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
84 documentation for more information.
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
85
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
86
4419
35444232ac7e Note about code duplication.
Matti Hamalainen <ccr@tnsp.org>
parents: 4416
diff changeset
87 - 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
88 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
89 Discuss about it with fellow developers.
35444232ac7e Note about code duplication.
Matti Hamalainen <ccr@tnsp.org>
parents: 4416
diff changeset
90
35444232ac7e Note about code duplication.
Matti Hamalainen <ccr@tnsp.org>
parents: 4416
diff changeset
91
4415
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
92
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
93 Additional style guidelines
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
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
96 - Indentation: Use the same indentation style (also spaces vs. tabs)
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
97 as the file you are editing. In new files/code, use indentation of
4417
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
98 4 spaces (no tabs). When moving functions to new files, PLEASE
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
99 reindent the code.
4415
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
100
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
101 - Whitespace usage in code:
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 a = 1;
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 if (b == d && !strcmp(a, c)) ...
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 - Blocks:
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
108
4417
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
109 while (...)
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
110 {
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
111 do_something(...);
4415
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
112 }
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
113
4417
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
114 if (...)
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
115 {
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
116 do_stuff();
4415
2c3390afe10e Added a coding guideline document.
Matti Hamalainen <ccr@tnsp.org>
parents:
diff changeset
117 }
4417
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
118 else
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
119 {
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
120 do_other_stuff();
f922499e69bc Fix typos, etc.
William Pitcock <nenolod@atheme.org>
parents: 4415
diff changeset
121 }