From 57df72caf8d749c7cd5f36117ff35e41975db3d3 Mon Sep 17 00:00:00 2001 From: zlg Date: Sat, 19 Dec 2015 18:37:40 -0800 Subject: Change license to GPLv3, add contributing guide * Improve README tone * Add `astylerc` for use with the astyle package * Add AUTHORS file to acknowledge contributors --- CONTRIBUTING.mdown | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 CONTRIBUTING.mdown (limited to 'CONTRIBUTING.mdown') diff --git a/CONTRIBUTING.mdown b/CONTRIBUTING.mdown new file mode 100644 index 0000000..3494ec6 --- /dev/null +++ b/CONTRIBUTING.mdown @@ -0,0 +1,119 @@ +Before contributing to this project, please read the following suggestions. +They'll make life easier for everyone. This file is somewhat of a work in +progress. Don't hesitate to ask about a situation that's not covered here: it +may lead to a more thorough document. + +# Commit Messages + +* Must be wrapped to 72 characters or less +* First line should indicate *what* was changed, in the present tense, e.g. + "Fix off-by-one error in foobar.c" + +# Acknowledgement + +If you wish to be acknowledged for your contributions, add your name (if it +isn't already present) to the AUTHORS file before commiting your changes so pull +requests already include the relevant information. The format should be: + + Firstname Lastname or Pseudonym + Brief summary of contributions, indented by four spaces. + +At least one of the four identifiers must be used, preferably whatever matches +your `.gitconfig` user information. + +Keep in mind that this project is also licensed under the GPL version 3. The +terms of the license can be found in the LICENSE file. Please do not contribute +to this project if the GPL 3 is not a satisfactory license for you. While some +licenses may be compatible with the GPL, licensing individual files with +different licenses between authors very quickly becomes a mess and would +diminish the value of this project. + +# Categories + +There are [three categories][clc-cats] of solutions to K&R exercises. This +project aims for Category-0 (zero) compliance, which means that only concepts +that have been covered *up to* the current exercise can be used, and the code +must adhere to the ANSI/ISO C89 standard. + +# Code Style + +* `snake_case` preferred. Shortened names are acceptable, e.g. `vectsize` in lieu + of `get_vector_size` +* K&R (AKA 1TBS) indenting should be used. Opening braces are not permitted to + be on their own line. +* Tabs are four spaces wide and are exclusively used for indenting +* Spaces may be used to align on `:` or `=`; never indentation +* Names not meant to be used directly should be preceded by an underscore +* Constants should be in `ALL_CAPS`; shortened names still okay +* Operators must have exactly one (1) space on both sides, e.g. `1 + 1` instead + of `1+1`. One exception is pointers; the `*` symbol must be directly before + the beginning of the variable or function name, e.g. `char *buffer;` +* If `;` or `,` are used in a multi-statement line, they must be followed by one + space, e.g. `for (foo = 0; foo < bar; foo++) {` +* Empty lines are not allowed inside blocks (and thus functions, including + `main()`) + +You can use the [astyle][astyle-home] package to run code through to ensure it +meets style guidelines. You'll need to run it like so: + + astyle -A2TpHUjSxek3W3 [filename] + +There is an `astylerc` file included in the repository for convenience. + +## Variable Names + +Try to use short, but descriptive variables for data that will be used +in a non-trivial way, i.e. not used as a one-off in a loop. In general, +shorthand variables `i`, `j`, and `k` are used for various loop levels, `c` for +characters, `s` for quick-and-dirty strings. Such shorthand names should only be +used when the name isn't very important. For example: + + int strlen(char *s) { + int i; + for (i = 0; s[i] != '\0'; i++) { + /* do stuff */ + } + return i; + } + +In the above, it'd be pointless for `s` to be something like `input_string` +because we know based on the function name and the type of `s` that we're +dealing with a simple C string and we're just getting its length. `i` could be +renamed to `length` and be more semantic, but in this case it'd be expanding +for little gain. To sum up, use your best judgment. If there's any chance for +ambiguity, use a better name. + +(Note: At the time of writing, the original author has some cleaning up to do, +too :P) + +## Function Names + +Much like variables, aim for something short, but descriptive. A lot of what's +in the K&R is given to you, so wherever possible, solutions should make use of +functions already made available in the text, or minor alterations thereof. + +## Comments + +C has two commenting syntaxes. Most projects prefer one or the other. Both +syntaxes are generally okay; however, since Category-0 solutions adhere to the +C89/C90 standard, only multi-line comments (`/* like this */`) should be used. + +At the time of writing, this is in need of correction and is already planned to +be retroactively fixed. + +Comment use in code should be minimal; if a comment is reiterating what's +already there, it's a bad comment. Comments should discuss *what* is going on if +it's not obvious, and/or *why* you're doing it. The following is pretty useless: + + int i; /* Array index */ + +But this can be useful for someone trying to follow along and learn: + + /* Subtract one from the string's length to account for the NUL terminator. + * This ensures that the correct length for actual string content is + * reported. + */ + return (len - 1); + +[clc-cats]: http://clc-wiki.net/wiki/K%26R2_solutions:Ancillary:Category_numbers +[astyle-home]: http://astyle.sourceforge.net -- cgit v1.2.3-54-g00ecf