About Coding Styles and Standards

# About Coding Styles and Standards

Achim Gsell, High Performance Computing and Emerging Technologies

February, 3., 2026

---
## ToC

* [The tool I used to create the slides](#Tool)
* [Introduction](#introduction)
* [Why?](#why)
* [A few general rules (not only for coding)]()
* [Coding styles and standards for C/C++ and Python]()
* [Some general rules you should follow]()
* [Comments]()
* [Linux kernel coding style]()
* [Tools]()
* [Git]()

---
## <a id="Tool"></a>The tool I used to create the slides

* I don't like Powerpoint an Co!
* ASCII format.
* Similar workflows as with software can be used.
* For this slides: `markdown-to-slides`
* It's on [Github](https://github.com/partageit/markdown-to-slides).

---
## Introduction

* how I came across this topic and why I consider it important
* once I had to fix an issue in the token ring driver in the Linux kernel
  * it was surprisingly easy to navigate through the kernel sources ...
  * to read ...
  * and to fix it.
  * The coding style was very helpful in this regard.
* an experience at PSI
  * a code developed by one (permanent) employee and PhD., Post-docs and and master students
  * no coding style, no bugtracking, no code review
  * the code was difficult to read, understand, maintained and extended.

---
## Why?

* You read code more often than you write code.
* In a team you should agree on some basic rules
* otherwise the code is dificult to read and understand.
* Good coding style helps you to write better code.

---
## A few general rules (not only for coding)

### Line length

```
" ... it is widely accepted that line lengths fall between 45 and
75 characters per line (cpl), though the ideal is 66 cpl ..."
```

```
"The experience of the reader can also be considered as a factor
when determining the count of characters within text lines. For
novice readers, text lines should contain between 34 and 60
characters, 45 being the optimal number. Texts for expert readers
could contain between 45 and 80 characters, with an optimal count
of 60 characters." 
```
[Wikipedia](https://en.wikipedia.org/wiki/Line_length#:~:text=In%20typography%2C%20line%20length%20is,%22%2C%20%22We%22)

---
### White space

```
"White space significantly impacts readability by making content
more legible and easier to consume. Ample spacing between lines,
paragraphs, and sections helps readers distinguish between
different pieces of information, allowing their eyes to rest and
preventing fatigue. It also helps guide the reader's eye and
improves the flow of reading, leading to better comprehension. 
Without appropriate white space, content can appear cluttered,
overwhelming, and difficult to read." 
```

[Lenovo](https://www.lenovo.com/us/en/glossary/white-space/?orgRef=https%253A%252F%252Fwww.google.com%252F)

---
### Complexity

```
"Any intelligent fool can make things bigger and more complex. It 
takes a bit of ingenuity – and a lot of courage – to move in the
opposite direction. "
```
Albert Einstein

=> Reduce things to the essentials and make them understandable.

---
### Don't re-invent the wheel

* Choose an existing coding style/standard and adapt it to your needs - if it is really necessary.
* Some simple rules can have a huge impact on code quality.
* Don't be dogmatic with concepts like early returns, goto's in C, ...

---
## Some styles and standards for C/C++
(See: [awesome C++](https://github.com/fffaraz/awesome-cpp)))

* Coding Standards
  * [Cert C++](https://resources.sei.cmu.edu/downloads/secure-coding/assets/sei-cert-cpp-coding-standard-2016-v01.pdf)
  * [Misra C++ 2008](https://www.cppdepend.com/misra-cpp)
  * [Autosar C++ 2014](https://www.autosar.org/fileadmin/standards/R21-11/AP/AUTOSAR_RS_CPP14Guidelines.pdf)
  * [F-35 Fighter Jet's C++ Coding Standards](https://www.stroustrup.com/JSF-AV-rules.pdf)
* Coding Style
  * [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines) - "Official" set of C++ guidelines, reviewed by the author of C++.
  * [C++ Dos and Don'ts](http://www.chromium.org/developers/coding-style/cpp-dos-and-donts) - The Chromium Projects > For Developers > Coding Style > C++ Dos and Don'ts.
  * [google-styleguide](https://github.com/google/styleguide) - Style guides for Google-originated open-source projects.
  * [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)
  * [GNU Coding Standard](http://www.gnu.org/prep/standards/standards.html)
  * [Linux kernel coding style](https://www.kernel.org/doc/Documentation/process/coding-style.rst)
  * [LLVM Coding Standards](http://llvm.org/docs/CodingStandards.html)

---
## Python coding styles
* [PEP 8](https://peps.python.org/pep-0008)
* [Real Python](https://realpython.com/ref/best-practices/coding-style/$0)
* [Google](https://google.github.io/styleguide/pyguide.html)

---
## Some general rules you should follow

* Fewer rules are often better.
* Be consistent
  * it's less important where to place spaces, parenteses, etc
  * same for CamelCase or foo_bar
* Follow best practices for the language.
* Use descriptive names.
* A function should do one thing.
* Functions should be short.
* Complex functions should be even shorter.

---
## Comments

```
Generally, a comment is an annotation intended to make the code easier
for a programmer to understand – often explaining an aspect that is
not readily apparent in the program (non-comment) code. 
```
[Wikipedia](https://en.wikipedia.org/wiki/Comment_(computer_programming)

---
### Comments (Ccont.)

Rule 1: Comments should not duplicate the code.

Rule 2: Good comments do not excuse unclear code.

Rule 3: If you can't write a clear comment, there may be a problem with the code.

Rule 4: Comments should dispel confusion, not cause it.

Rule 5: Explain unidiomatic code in comments.

Rule 6: Provide links to the original source of copied code.

Rule 7: Include links to external references where they will be most helpful.

Rule 8: Add comments when fixing bugs.

Rule 9: Use comments to mark incomplete implementations.

Stackoverflow: [Best practices](https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/)

---
## Linux kernel coding style

[Linux kernel coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html)

* Linux: 8(!) spaces per level.
* Max line length: 80 chars.
* This limits the numer of levels - usually not more than 3 levels.
* You have to structure your code better.
* => use a function for a code block (even if they are called only
  once)
  ```
  if condition:
          do_this()
  else:
          do_that()
  ```
* Forget the performance penalty of calling a function (there are exception).
* Use inline function with care (C/C++).
* More functions also (usually) means: less arguments per function => easier to read and understand.
  
---
## Examples Linux kernel

* [core socket implementation](https://github.com/torvalds/linux/blob/master/net/core/sock.c)
* [fsync() implementation in ext4 filesystem](https://github.com/torvalds/linux/blob/master/fs/ext4/fsync.c)

---
## Tools for static code analysis (C/C++)
(See: [awesome C++](https://github.com/fffaraz/awesome-cpp)))

* [Cppcheck](http://cppcheck.sourceforge.net/) - A tool for static C/C++ code analysis. - [source](https://github.com/danmar/cppcheck)
* [CppDepend](https://www.cppdepend.com/) - Simplifies managing a complex C/C++ code base by analyzing and visualizing code dependencies, by defining design rules, by doing impact analysis, and comparing different versions of the code.
* [cpplint](https://github.com/cpplint/cpplint) - A C++ style checker following Google's C++ style guide.
* [PVS-Studio](http://www.viva64.com/en/pvs-studio/) - A tool for bug detection in the source code of programs, written in C, C++ and C#.
* [cpp-dependencies](https://github.com/tomtom-international/cpp-dependencies) - Tool to check C++ #include dependencies (dependency graphs created in .dot format). [Apache]
* [include-what-you-use](https://github.com/include-what-you-use/include-what-you-use) - A tool for use with clang to analyze includes in C and C++ source files. [website](https://include-what-you-use.org/)
* [Infer](https://github.com/facebook/infer) - A static analyzer for Java, C and Objective-C. [BSD]
* [OCLint](http://oclint.org/) - A static source code analysis tool to improve quality and reduce defects for C, C++ and Objective-C. - [source](https://github.com/oclint/oclint)
* [Clang Static Analyzer](http://clang-analyzer.llvm.org/index.html) - A source code analysis tool that finds bugs in C, C++, and Objective-C programs.
* [Linticator](http://linticator.com) - Eclipse CDT integration of Pc-/FlexeLint.
* [IKOS](https://github.com/NASA-SW-VnV/ikos) - Static analyzer for C/C++ based on the theory of Abstract Interpretation. [NOSA 1.3]
* [OptView2](https://github.com/OfekShilon/optview2) - Inspect missed Clang optimizations.
* [Trunk](https://trunk.io) - Toolkit to check, test, merge, and monitor code.

## Coding Style Tools (C/C++)

* [Artistic Style](http://astyle.sourceforge.net/) - A tool to format C/C++/C#/Obj-C/Java code. Also known as astyle.
* [ClangFormat](http://clang.llvm.org/docs/ClangFormat.html) - A tool to format C/C++/Obj-C code.
* [Clang-Tidy](http://clang.llvm.org/extra/clang-tidy.html) - Clang-based C++ linter tool.
* [EditorConfig](https://editorconfig.org/) - EditorConfig helps maintain consistent coding styles across different editors and IDEs.
* [Uncrustify](https://github.com/uncrustify/uncrustify) - Code beautifier.

---
## Code Analysis (Python)

See [Awesome Python](https://github.com/vinta/awesome-python#readme)

- Code Analysis
  - [code2flow](https://github.com/scottrogowski/code2flow) - Turn your Python and JavaScript code into DOT flowcharts.
  - [prospector](https://github.com/PyCQA/prospector) - A tool to analyze Python code.
  - [vulture](https://github.com/jendrikseipp/vulture) - A tool for finding and analyzing dead Python code.
- Code Linters
  - [flake8](https://github.com/PyCQA/flake8) - A wrapper around `pycodestyle`, `pyflakes` and McCabe.
    - [awesome-flake8-extensions](https://github.com/DmytroLitvinov/awesome-flake8-extensions)
  - [pylint](https://github.com/pylint-dev/pylint) - A fully customizable source code analyzer.
  - [ruff](https://github.com/astral-sh/ruff) - An extremely fast Python linter and code formatter.
- Code Formatters
  - [black](https://github.com/psf/black) - The uncompromising Python code formatter.
  - [isort](https://github.com/timothycrosley/isort) - A Python utility / library to sort imports.
  - [yapf](https://github.com/google/yapf) - Yet another Python
    code formatter from Google.
	
---
## Code Analysis (Python, cont.)

- Static Type Checkers, also see [awesome-python-typing](https://github.com/typeddjango/awesome-python-typing)
  - [mypy](https://github.com/python/mypy) - Check variable types during compile time.
  - [pyre-check](https://github.com/facebook/pyre-check) - Performant type checking.
  - [ty](https://github.com/astral-sh/ty) - An extremely fast Python type checker and language server.
  - [typeshed](https://github.com/python/typeshed) - Collection of library stubs for Python, with static types.
- Static Type Annotations Generators
  - [monkeytype](https://github.com/Instagram/MonkeyType) - A system for Python that generates static type annotations by collecting runtime types.
  - [pytype](https://github.com/google/pytype) - Pytype checks and infers types for Python code - without requiring type annotations.

---
## Git

* use Git hooks
* use pipelines to check code quality before merging

---
## Questions