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++
• Python
• PHP
• HTML and CSS

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 or GitHub Flavored Markdown for text files
• Consider using PlantUML 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 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):

• 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!