Skip to content

Latest commit

 

History

History
187 lines (129 loc) · 4.66 KB

contributing.md

File metadata and controls

187 lines (129 loc) · 4.66 KB
Raw

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 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.