1 =======================
2 Contribution Guidelines
3 =======================
4
5 This is a short document describing the preferred coding style for this project
6
7
8 Indentation
9 ===========
10
11 Indentation is two spaces.
12
13 While some, if not most people may disagree with this (Linus, I'm looking at
14 you), this is the current standard for this project. Some standards deviating
15 from will have little impact, but deviating from this standard will be quite
16 noticeable, so please adhere to it.
17
18 If you particularly disagree with it enough, please contact the project owner
19 and they (I) might be persuaded to change it to 4 spaces (but never tabs).
20
21 Rationale: If you notice the 'Line Width' section, you will see that lines are
22 to be no more than 80 characters wide (though there are exceptions). Having a
23 4, 8, or even greater character indentiation might increase readability from an
24 indentation perspective, but will decrease readability as lines are
25 unecessarily broken because not enough space remains on the line after said
26 indentation.
27
28
29 However, if you find your indentations don't leave you enough space with an 80
30 character width, refer to this quote from Linus Torvalds.
31
32
33 Now, some people will claim that having 8-character *[or 2 in our case]*
34 indentations makes the code move too far to the right, and makes it hard to
35 read on a 80-character terminal screen. The answer to that is that if you need
36 more than 3 levels of indentation, you're screwed anyway, and should fix your
37 program.
38
39
40
41 Trailing Whitespace
42 ===================
43
44 ...is never acceptable. Most IDEs warn you about this, git warns you about
45 this, I'm warning you about this. Heed the warnings.
46
47
48 Functions
49 =========
50
51 Functions should be defined using the POSIX standard style. They should look
52 like...
53
54 **Example**::
55
56 foo() {
57 printf "Hello World\n"
58 }
59
60
61 Rationale: This program has the possibility of running on devices that do not
62 have bash installed. Having non-POSIX compliant function definitions will
63 likely reduce the number of devices this script can run on, as most devices
64 only come with the ash or dash shells.
65
66
67 Variables inside of functions need to be scope locally.
68
69 **Example**::
70
71 foo() {
72 local arg=${1}
73 local matey=${2}
74
75 printf "Hello World\n"
76 }
77
78 Having variables scoped locally will reduce the likelyhood of overwriting the
79 same named variable that exists outside of the function.
80
81
82 POSIX Compliance
83 ================
84
85 Always do your best to stay within the `POSIX shell scripting standards`_. As
86 unfortunate and limiting as this is, most Android devices come only with shells
87 that implement the minimum to be POSIX compliant. Any scripting code that
88 exceeds the POSIX standards will likely break compatibility with a number of
89 devices (if not all devices).
90
91 .. _POSIX shell scripting standards: http://pubs.opengroup.org/onlinepubs/9699919799/
|
