Skip to content

Commit

Permalink
For issue #2.
Browse files Browse the repository at this point in the history
Add an initial coding style guide document.
  • Loading branch information
louis-langholtz committed Sep 9, 2017
1 parent 443c953 commit 4b1dd7a
Show file tree
Hide file tree
Showing 2 changed files with 73 additions and 2 deletions.
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,6 @@ probably don't need to do it again.
* :arrow_down: `:arrow_down:` when downgrading dependencies.
* :shirt: `:shirt:` when removing linter warnings.

### C++ Style Guide
### C++ Coding Style Guide

Generally speaking, follow the style of the existing code.
Generally speaking, follow the style of the existing code. More specifically though, see the [Style Guide](Documentation/StyleGuide.md).
71 changes: 71 additions & 0 deletions Documentation/StyleGuide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# PlayRho Library Style Guide

This is the style guide for the PlayRho library. This guide is meant for contributors who want to contribute pull requests for code changes.

For general information on contributing, see the [Contributing](../CONTRIBUTING.md) document.

## General Guidelines

### Follow The C++ Core Guidelines For Anything Not Described Herein
For anything not described herein, please follow the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md).

### C++14 Is The Applicable Standard
Write code to the C++14 standard. Try to document any changes recommended for C++17.

### Notes

- Just because a guideline is listed in this document, does not mean that it's a *good* guideline (or a *bad* one for that matter).
- Some of the guidelines described herein are established primarily by precedence from the history of this code.

### Available Tools

Here are some links to available tools for style conformance. Unfortunately they don't seem perfectly up to the job by themselves so it's still necessary to be aware of the guidelines:

- [`.editorconfig`](../.editorconfig): Configuration file for [EditorConfig](http://editorconfig.org).
- [`.clang-format`](../.clang-format): Configuration file for clang-format.

## Formatting

### General Formatting Guideline For Pre-existing Code
Generally speaking, don't change the formatting of pre-existing code.

### Code Indentation
Code indentation should be done using 4-spaces for every level of code indentation desired. Tabs should not be used for this.

### Class Head Names Begin With Capitalized Letter
Both `class` and `struct` class definition names should begin with a capitalized letter.

## Naming

### Use More Self-Explanatory Names For More Widely Used Definitions
Globally accessible definitions should generally be composed of full words that explain them. Definitions used in smaller contexts can be increasingly tersely named and abbreviated.

### Conjoin Multi Word Names With The First Letter Of New Words Capitalized
Unless the definition is meant to be replaceable with a Standard Library definition, names should be camel-case separated. Definitions meant to be replaceable with Standard Library definitions meanwhile should mimic the naming style of the definitions they're meant to be interchangeable with.

## Functions

### Function Names Usually Begin With Capitalized Letter
The first letter of every function should be capitalized **unless** the function is intended to be a candidate for replacement by a Standard Library function or method.

### Generally Function Names Start With Their Action
The names of all functions — whether non-static member functions, static member functions, non-member functions, etc. — should start with the action that they perform. For example: `Get*`, `Set*`, `Find*`, `Transform*`, `Create*`, `Destroy*`, `Insert*`, `Erase*`

### Boolean Constant Member Function Names May Start With The Question They Answer
For example: `IsSleepingAllowed`, `NeedsFiltering`, or `HasValidToi`.

## Variables

### Begin With A Lower-Case Letter

### Begin `class`-class Member Variable Names With `m_`

## Documentation

### Doxygen Style Comment Documentation Is To Be Used

### Every Definition Should Include Documentation Comments
Code missing Doxygen documentation won't pass all of the Pull Request checks and is unlikely to be accepted.

### Every `class`-class Should Document Its Invariants
This is especially the case for any new classes. Lots of existing `class`-class definitions don't document any invariants but they should. Make it a habit to document invariants in a class definition or use the `struct`-class if the class is not supposed to have any invariants.

0 comments on commit 4b1dd7a

Please sign in to comment.