355 lines
13 KiB
HTML
355 lines
13 KiB
HTML
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>About Coding Styles and Standards</title>
|
||
<style>
|
||
body {
|
||
font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
|
||
}
|
||
h1, h2, h3 {
|
||
font-weight: 400;
|
||
margin-bottom: 0;
|
||
}
|
||
.remark-slide-content h1 { font-size: 3em; }
|
||
.remark-slide-content h2 { font-size: 2em; }
|
||
.remark-slide-content h3 { font-size: 1.6em; }
|
||
.footnote {
|
||
position: absolute;
|
||
bottom: 3em;
|
||
}
|
||
li p { line-height: 1.25em; }
|
||
.red { color: #fa0000; }
|
||
.large { font-size: 2em; }
|
||
a, a > code {
|
||
color: rgb(249, 38, 114);
|
||
text-decoration: none;
|
||
}
|
||
code {
|
||
background: none repeat scroll 0 0 #F8F8FF;
|
||
border: 1px solid #DEDEDE;
|
||
border-radius: 3px ;
|
||
padding: 0 0.2em;
|
||
}
|
||
.remark-code, .remark-inline-code { font-family: "Bitstream Vera Sans Mono", "Courier", monospace; }
|
||
.remark-code-line-highlighted { background-color: #373832; }
|
||
.pull-left {
|
||
float: left;
|
||
width: 47%;
|
||
}
|
||
.pull-right {
|
||
float: right;
|
||
width: 47%;
|
||
}
|
||
.pull-right ~ p {
|
||
clear: both;
|
||
}
|
||
#slideshow .slide .content code {
|
||
font-size: 0.8em;
|
||
}
|
||
#slideshow .slide .content pre code {
|
||
font-size: 0.9em;
|
||
padding: 15px;
|
||
}
|
||
.main-title, .title {
|
||
background: #272822;
|
||
color: #777872;
|
||
text-shadow: 0 0 20px #333;
|
||
}
|
||
.title h1, .title h2, .main-title h1, .main-title h2 {
|
||
color: #f3f3f3;
|
||
line-height: 0.8em;
|
||
}
|
||
/* Custom */
|
||
.remark-code {
|
||
display: block;
|
||
padding: 0.5em;
|
||
}
|
||
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<textarea id="source">
|
||
# About Coding Styles and Standards
|
||
|
||
<img src="pexels-pixabay-270348.jpg" alt="code" style="width: 80%;">
|
||
|
||
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
|
||
|
||
</textarea>
|
||
<script src="remark-latest.min.js"></script>
|
||
<script>
|
||
var slideshow = remark.create();
|
||
</script>
|
||
<script></script>
|
||
</body>
|
||
</html>
|