Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Adds contributing file.

More information on how the new contributing files work at github
[here](https://github.com/blog/1184-contributing-guidelines)
  • Loading branch information...
commit b9cc6fc933563ce07f1f178e848800bafce64813 1 parent 39cd4ee
@cknadler cknadler authored
Showing with 187 additions and 0 deletions.
  1. +187 −0 contributing.md
View
187 contributing.md
@@ -0,0 +1,187 @@
+# hkl programming standards
+___
+
+### Naming Conventions
+---
+
+* __Classes, Enums__:
+
+ Format: PascalCase
+
+ Ex:
+
+ HklString
+ HklObject
+ HklState
+
+* __Methods, Local Variables__:
+
+ Format: underscore_delimited
+
+ Rules:
+ * All methods and variables must have meaningful names
+ * Try to be as descriptive as possible and stay away from single character variables
+
+ Ex:
+
+ HklString* hkl_string_new_from_utf8(const char* utf8string);
+ static void hkl_string_reverse(HklString* const str);
+ int argument_count;
+
+* __Constants, Enum Values, Macros__:
+
+ Format: UPPER_CASE
+
+ Ex:
+
+ static const uint32_t HKL_UTF8_MASKS[6] =
+ {
+ // Stuff
+ };
+
+### Formatting
+---
+
+__General__
+
+* No hard tabs
+* Indent two spaces
+
+__Braces__
+
+All braces on individual lines:
+
+ if (some_bool)
+ {
+ // Code
+ }
+
+No TIE Fighter else statments:
+
+ if (some_bool)
+ {
+ // Code
+ }
+ else
+ {
+ // More code
+ }
+
+Enums are an exception:
+
+ typedef enum
+ {
+ RED,
+ BLUE,
+ GREEN
+ } EnumName;
+
+Always use brackets, even in single line statements:
+
+ if (some_bool)
+ {
+ return something;
+ }
+
+
+### Documentation
+---
+
+__Doxygen__
+
+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.
+
+__Functions__
+
+Every function must be documented with the following:
+
+* // Brief Description of the function(10 words or so)
+* // @pre The condition/state required before a call (can be None)
+* // @post The condition/state after the function is called (can be None)
+* // @param paramName (each param gets its own line for this
+* // @retval ReturnType What this value represents
+* // @brief Describe the functions purpose, methodology, etc
+
+ex:
+
+ /**
+ Reverses strings
+
+ @pre None
+ @post None
+ @param str: A pointer to a string to be reversed
+ @retval None
+ @brief Takes a pointer to a string and reverses it. For example, dog -> god.
+ */
+ static void hkl_string_reverse(HklString* const str)
+ {
+ // Logic
+ }
+
+
+__Structs__
+
+Note, this should go at the top of the `.h` file of the class.
+
+* // @struct ClassName brief description approx one sentence
+* // 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
+* // @author/@authors (comma seperated if more than one)
+* // @date for creation (maybe each time it is updated after its first version?)
+
+ex:
+
+ /**
+ @struct HklExpression: Facilitates expression storage and evaluation
+
+ HklExpression allows for the storage of three major types of expressions; binary expressions, unary expressions and variable expressions.
+ @authors Scott LaVigne, Jennifer Coryell
+ @date 08/23/12
+ */
+
+
+### Version Control
+---
+
+__Git__:
+
+Commit messages are important. Rules are as follows and stolen wholesale from Tim Pope:
+
+```
+Capitalized, short (50 chars or less) summary
+More detailed explanatory text, if necessary. Wrap it to about 72
+characters or so. In some contexts, the first line is treated as the
+subject of an email and the rest of the text as the body. The blank
+line separating the summary from the body is critical (unless you omit
+the body entirely); tools like rebase can get confused if you run the
+two together.
+
+Write your commit message in the present tense: "Fix bug" and not "Fixed
+bug." This convention matches up with commit messages generated by
+commands like git merge and git revert.
+
+Further paragraphs come after blank lines.
+
+- Bullet points are okay, too
+
+- Typically a hyphen or asterisk is used for the bullet, preceded by a
+ single space, with blank lines in between, but conventions vary here
+
+- Use a hanging indent
+```
+
+__Workflow__:
+
+You should be comfortable with Git.
+
+Everyone branches from the orginization so that we can all work on a "disposable" repo
+I like this because if we are careful we can use these to keep detailed records of individual
+work and at the same time have a less likely chance of causing issues with the main repo.
+
+When work is finished and some feature or bug fix is ready to be implemented the fixer will
+basically squash the commits into a giant one.
+This is easy to do if you commit to a feature branch then squash it to merge it into main.
+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).
+Then we will be able to submit a pull request.
+
+No one should accept their own pull request, but some other user(s) should vet it first and
+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.
Please sign in to comment.
Something went wrong with that request. Please try again.