migrate from github gist and cleanup/ update content
This commit is contained in:
parent
b1047c016c
commit
563152732d
64
README.md
64
README.md
|
|
@ -1,6 +1,62 @@
|
|||
# guidelines-coding-style
|
||||
Author: Jannik Beyerstedt
|
||||
**license:** CC BY-SA 4.0
|
||||
# Coding Style Guidelines
|
||||
|
||||
This is my (currently quite messy) collection of coding styles and other coding related rules.
|
||||
Most things should be quite generally applicable and common sense, some others might just be my personal taste.
|
||||
But feel free to use this as a base for your own style or even comment/ contribute to this.
|
||||
|
||||
## Structure
|
||||
This file contains some general rules, which apply to most programming languages.
|
||||
Individual style guides are available in other files for:
|
||||
- [C/C++](Style-Cpp.md)
|
||||
- [Python](Style-Python.md)
|
||||
- [PHP](Style-PHP.md)
|
||||
|
||||
Also see my project dotfiles and templates in: https://git.beyerstedt.de/jannik/templates-project_setup
|
||||
|
||||
|
||||
My coding style guidelines for different programming languages.
|
||||
## General Workflow
|
||||
|
||||
- Use a version control system, e.g. Git
|
||||
- Couple your documentation versioning to the source code
|
||||
* Write documentation as plain text files, e.g. in Markdown syntax
|
||||
* If reasonably possible, also provides model and diagram sources. But do not put large binary blobs in the repository.
|
||||
|
||||
### Documentation
|
||||
- Use [Markdown](https://daringfireball.net/projects/markdown/syntax) or [GitHub Flavored Markdown](https://github.github.com/gfm/) for text files
|
||||
- Consider using [PlantUML](https://plantuml.com) for diagrams (because it's source is text based and can be versioned)
|
||||
|
||||
### Files
|
||||
- File and folder names (of your source code) should:
|
||||
* Just contain lower case characters
|
||||
* Not contain spaces
|
||||
* Separate prefixes with a dash and words with an underscore, like `topic-foo_bar.txt`
|
||||
* Contain none of these special characters `|/\~!?=^%&$`
|
||||
- Structure your code in a reasonable way into folders
|
||||
|
||||
### Git
|
||||
General rules:
|
||||
- Use it!
|
||||
- Do not commit binary blobs (or have a good reason for it)
|
||||
- Never commit
|
||||
- List things, that should not be committed, in the `.gitignore` file. (Use [readily available templates](https://github.com/github/gitignore) for your programing language)
|
||||
- Only commit a state, which at least compiles without errors and even better is a runnable version
|
||||
|
||||
Commits:
|
||||
- Commits should contain one single/ standalone change or (step towards a) feature
|
||||
- The code state in a commit should
|
||||
* at least compile without errors
|
||||
* better: compile without warnings
|
||||
* best: be tested to run as expected
|
||||
- Commit messages should:
|
||||
* The description should use imperative language in present tense, e.g. `fix bug`/ `add new form field`
|
||||
* If only a certain module was changed, prefix the description with the module name, e.g. `moduleX: add some more logging`
|
||||
* Use a tag to annotate special changes, like:
|
||||
+ `[DOC]`: if only documentation was changed
|
||||
+ `[FIX]`: for bug fixes
|
||||
+ `[TIDY]`: for refactoring actions and other cleanup steps. No functionality should be changed here!
|
||||
|
||||
Branching Model (adapted from [git-flow](http://nvie.com/posts/a-successful-git-branching-model/)):
|
||||
- First of all, take use of the branches!
|
||||
- Use a master branch for the current stable version AND a `develop` branch for the current state of development
|
||||
- Use branches named `feature/$your_feature_name` to develop features without interfering with the develop branch.
|
||||
- Therefore: Use a branch and merge (Pull request/ Merge Request) workflow. Even if your on your own!
|
||||
|
|
|
|||
|
|
@ -0,0 +1,155 @@
|
|||
# Coding Style for C/ C++
|
||||
|
||||
TODO: Update with less details/ more references to CppCoreGuidelines and auto-formatting.
|
||||
|
||||
|
||||
## OLD/ EXISTING STUFF
|
||||
|
||||
UPDATE: Take a look at http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines.
|
||||
|
||||
### general
|
||||
- write in english
|
||||
- make your code beautiful to read! e.g. intend all `#define` values to the same column
|
||||
- use UNIX line breaks `\n` instead of DOS `\r\n`
|
||||
- indent code by 2 spaces for each level, no tabs!
|
||||
- every file ends with one blank line (newline at EOF)
|
||||
- no trailing white space should be committed! (except markdown of course)
|
||||
|
||||
|
||||
### variables, functions and classes naming
|
||||
```c++
|
||||
#define SOME_DEFINE
|
||||
int someInteger = 0;
|
||||
void functionName(int param) {}
|
||||
class ClassName {
|
||||
void someMethod() {}
|
||||
}
|
||||
```
|
||||
- use camelCase, except preprocessor directives
|
||||
- underscores could be used for separating "prefixes" for organizing variables
|
||||
- use names describing the function of the variable/ function/ method.
|
||||
|
||||
#### preprocessor directives
|
||||
- all upper case, separating word by an underscore (`SOME_DEFINE`)
|
||||
|
||||
#### variables
|
||||
- camelCase, beginning with a lower case character (`someVariable`)
|
||||
|
||||
#### functions
|
||||
- camelCase, beginning with an lower case character (`someFunction()`)
|
||||
|
||||
#### classes: class name, methods and class/ instance variables
|
||||
- classes: camelCase, beginning with an upper case character (`SomeClass`)
|
||||
- methods: camelCase, beginning with a lower case character (`someClassMethod()`)
|
||||
- private variables: camelCase, ending with an underscore, beginning with a lower case character (`somePrivateVariable_`)
|
||||
|
||||
|
||||
### white space and braces in basic structures
|
||||
For the eclipse IDE, please use the code style formatter file attached in this Gist. Import it by selecting `Settings -> C/C++ -> Code Style -> Formatter`.
|
||||
|
||||
```c++
|
||||
int main() {
|
||||
int foo = 0;
|
||||
|
||||
for (int i = 0; i < 10; i++) {
|
||||
foo = myFunction(i);
|
||||
}
|
||||
|
||||
if (foo > 3) {
|
||||
// do a
|
||||
} else {
|
||||
printf("foobar");
|
||||
}
|
||||
|
||||
while (i <= 2) {
|
||||
i++;
|
||||
}
|
||||
|
||||
switch (foo) {
|
||||
case 1:
|
||||
// do 1
|
||||
break;
|
||||
|
||||
case 2:
|
||||
// do 2
|
||||
break;
|
||||
|
||||
default:
|
||||
// do nothing in default
|
||||
}
|
||||
}
|
||||
|
||||
int myFunction(int param) {
|
||||
return param;
|
||||
}
|
||||
|
||||
class MyRessource {
|
||||
public:
|
||||
MyRessource() {}
|
||||
virtual ~MyRessource(){}
|
||||
MyRessource(const MyRessource&){} MyRessource& operator=(const MyRessource&){}
|
||||
private:
|
||||
void* handle_;
|
||||
};
|
||||
```
|
||||
|
||||
- no trailing white space!
|
||||
|
||||
#### functions
|
||||
- no white space between function name and argument
|
||||
|
||||
#### instructions and conditions
|
||||
- in conditions checking for equality (`==`), write the variable to the right!
|
||||
- separate the operator from the arguments by a white space to improve legibility, e.g. `a <= b` instead of `a<=b`.
|
||||
|
||||
#### curly braces
|
||||
- use them every time! Even if the C syntax allows if and while statements to have a single instruction without curly braces surrounding the instruction.
|
||||
- set the opening curly brace in the same row as the statement, close them in a new line after the last instruction
|
||||
|
||||
#### if, while, switch-case
|
||||
- add a white space between the keyword and the opening brace of the condition
|
||||
- add a white space between the closing brace of the condition and the opening curly brace
|
||||
- add a white space before an `else`, the `else` keyword is on the same line as the closing bracket of the if-part
|
||||
|
||||
|
||||
### other, non formatting specific, coding guidelines and hints
|
||||
|
||||
#### includes and header files
|
||||
- include most specific first, standard library last
|
||||
- internal classes (only for this module) should only be declared in the cpp file, not in the header, because they are not part of the interface. (The header file is what defines the interface of a C++ module)
|
||||
- if anotherclass is used **as variable**, it's header file must be included.
|
||||
If it's only used **by reference** only use a forward declaration (`class FooBar;` at the beginning of the header file).
|
||||
If necessary include the header file of the used class in the **.cpp file**, e.g. if some method of the class FooBar is used in the implementation.
|
||||
|
||||
#### C++ classes implementation hints
|
||||
- use RAII (resource aquisition is initialization)
|
||||
|
||||
- use initialization at CTOR (init list) (since C++11)
|
||||
```c++
|
||||
class MyClass {
|
||||
public:
|
||||
MyClass(int a, float b) : somePrivateVariable_(a), someOtherVar_(b) {}
|
||||
private:
|
||||
int somePrivateVariable_;
|
||||
float someOtherVar_;
|
||||
};
|
||||
```
|
||||
|
||||
- use rule of three: A class which binds a resource, must provide: CTOR and DTOR, copy CTOR, assignment operator.
|
||||
Define copy CTOR and assignment as private, if these operations should not be possible.
|
||||
```c++
|
||||
class MyRessource {
|
||||
public:
|
||||
MyRessource() {}
|
||||
virtual ~MyRessource(){}
|
||||
MyRessource(const MyRessource&){} MyRessource& operator=(const MyRessource&){}
|
||||
private:
|
||||
void* handle_;
|
||||
};
|
||||
```
|
||||
|
||||
- use of `const`:
|
||||
- `int getValue() const {return val;}` ==> the corresponding class will not be changed
|
||||
- `void foo(const BigClass& c, OtherClass& d);` ==> only const functions of `BigClass` can be called
|
||||
- `const int MAX_VALUE = 1234;` is stored in ROM, but cannot be changed
|
||||
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# Coding Style for PHP
|
||||
|
||||
TODO
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# Coding Style for Python
|
||||
|
||||
TODO
|
||||
Loading…
Reference in New Issue