64 lines
3.1 KiB
Markdown
64 lines
3.1 KiB
Markdown
# 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)
|
|
- [HTML and CSS](Style-HTML_CSS.md)
|
|
|
|
Also see my project dotfiles and templates in: https://git.beyerstedt.de/jannik/templates-project_setup
|
|
|
|
|
|
## 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!
|