Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 187 lines (129 sloc) 4.775 kb
b9cc6fc @cknadler Adds contributing file.
cknadler authored
1 # hkl programming standards
2 ___
3
4 ### Naming Conventions
5 ---
6
7 * __Classes, Enums__:
8
9 Format: PascalCase
10
11 Ex:
12
13 HklString
14 HklObject
15 HklState
16
17 * __Methods, Local Variables__:
18
19 Format: underscore_delimited
20
21 Rules:
22 * All methods and variables must have meaningful names
23 * Try to be as descriptive as possible and stay away from single character variables
24
25 Ex:
26
27 HklString* hkl_string_new_from_utf8(const char* utf8string);
28 static void hkl_string_reverse(HklString* const str);
29 int argument_count;
30
31 * __Constants, Enum Values, Macros__:
32
33 Format: UPPER_CASE
34
35 Ex:
36
37 static const uint32_t HKL_UTF8_MASKS[6] =
38 {
39 // Stuff
40 };
41
42 ### Formatting
43 ---
44
45 __General__
46
47 * No hard tabs
48 * Indent two spaces
49
50 __Braces__
51
52 All braces on individual lines:
53
54 if (some_bool)
55 {
56 // Code
57 }
58
59 No TIE Fighter else statments:
60
61 if (some_bool)
62 {
63 // Code
64 }
65 else
66 {
67 // More code
68 }
69
70 Enums are an exception:
71
72 typedef enum
73 {
74 RED,
75 BLUE,
76 GREEN
77 } EnumName;
78
79 Always use brackets, even in single line statements:
80
81 if (some_bool)
82 {
83 return something;
84 }
85
86
87 ### Documentation
88 ---
89
90 __Doxygen__
91
92 Doxygen should be used for documentation generation. Check out the [Doxygen comment guide](http://www.stack.nl/~dimitri/doxygen/docblocks.html) for more information on Doxygen syntax.
93
94 __Functions__
95
96 Every function must be documented with the following:
97
98 * // Brief Description of the function(10 words or so)
99 * // @pre The condition/state required before a call (can be None)
100 * // @post The condition/state after the function is called (can be None)
101 * // @param paramName (each param gets its own line for this
102 * // @retval ReturnType What this value represents
103 * // @brief Describe the functions purpose, methodology, etc
104
105 ex:
106
107 /**
108 Reverses strings
109
110 @pre None
111 @post None
112 @param str: A pointer to a string to be reversed
113 @retval None
114 @brief Takes a pointer to a string and reverses it. For example, dog -> god.
115 */
116 static void hkl_string_reverse(HklString* const str)
117 {
118 // Logic
119 }
120
121
122 __Structs__
123
124 Note, this should go at the top of the `.h` file of the class.
125
126 * // @struct ClassName brief description approx one sentence
127 * // Longer description (I believe each line needs to start with the // isntead of /* */). This should include what the class solves, how it solves it, why it is there
128 * // @author/@authors (comma seperated if more than one)
129 * // @date for creation (maybe each time it is updated after its first version?)
130
131 ex:
132
133 /**
134 @struct HklExpression: Facilitates expression storage and evaluation
135
136 HklExpression allows for the storage of three major types of expressions; binary expressions, unary expressions and variable expressions.
137 @authors Scott LaVigne, Jennifer Coryell
138 @date 08/23/12
139 */
140
141
142 ### Version Control
143 ---
144
145 __Git__:
146
147 Commit messages are important. Rules are as follows and stolen wholesale from Tim Pope:
148
149 ```
150 Capitalized, short (50 chars or less) summary
151 More detailed explanatory text, if necessary. Wrap it to about 72
152 characters or so. In some contexts, the first line is treated as the
153 subject of an email and the rest of the text as the body. The blank
154 line separating the summary from the body is critical (unless you omit
155 the body entirely); tools like rebase can get confused if you run the
156 two together.
157
158 Write your commit message in the present tense: "Fix bug" and not "Fixed
159 bug." This convention matches up with commit messages generated by
160 commands like git merge and git revert.
161
162 Further paragraphs come after blank lines.
163
164 - Bullet points are okay, too
165
166 - Typically a hyphen or asterisk is used for the bullet, preceded by a
167 single space, with blank lines in between, but conventions vary here
168
169 - Use a hanging indent
170 ```
171
172 __Workflow__:
173
174 You should be comfortable with Git.
175
176 Everyone branches from the orginization so that we can all work on a "disposable" repo
177 I like this because if we are careful we can use these to keep detailed records of individual
178 work and at the same time have a less likely chance of causing issues with the main repo.
179
180 When work is finished and some feature or bug fix is ready to be implemented the fixer will
181 basically squash the commits into a giant one.
182 This is easy to do if you commit to a feature branch then squash it to merge it into main.
183 The commmit message can then be a long one detailing issues that were solved, feature implementations, etc in one commit message (therefore easier to read).
184 Then we will be able to submit a pull request.
185
186 No one should accept their own pull request, but some other user(s) should vet it first and
187 then pull it in if it works. The reason for this is that we will garuntee that all features were at least looked at or tested by a second person distributing the work and hopefully it will help us detect errors.
Something went wrong with that request. Please try again.