Keep it simple and solid, let the toolchain be smart,
code correctness is the duty, readability the art.
The goal of these conventions is to be concise, universal, and remarkable. It targets emerging code enthusiasts under time pressure and covers 7 topics:
- General Clarifications (Keep Consistency • Break rules • Improve Code • Terms)
- Architecture (Low Coupling • Coherent Abstraction)
- Implementation (DRY • Small Scopes • Express Ideas • Sort Args • Compose)
- Naming (Pick One • Bools • Subprograms • Types • Variables • Word Pairs)
- Code Layout
- Documentation (Comments • TODOs • Readmes • Logging • File Headers • Docstrings)
- Languages (Python • C • JavaScript)
To follow this guide, you should already have heard about Object Oriented Programming and know basic programming rules, such as writing loops and meaningful functions instead of copy pasting instructions.
“Consistency with this guide is important. Consistency within a project is more important. Consistency within one module or function is the most important” [PEP8].
Do not blindly follow this guide but think for yourself. The goal of software development is keeping the code complexity low. Period. None of the rules and fancy patterns matters if the code becomes impossible to maintain.
We all have seen bad code, we all have written bad code. Code tends to get messy over time. Therefore, do not only complain about bad code but improve it if you know how. If you don't care to do it, why should anyone else?
To be universal, we group several concepts under these broad identifiers:
- Scope = {Module, File, Namespace, Subprogram}
- Subprogram = {Procedure, Function, Method}
- Type = {Primitive, Collection, Struct, Class, ...}
- Collection = {Array, List, Tuple, Dict, Map, ...}
To manage complexity, divide your software into smaller parts (scopes) such as modules, classes, and subprograms. Where to separate and where to connect scopes is the art of good architecture.
Two common mistakes in architecture design are the creation of a monster class that has too many responsibilities and letting each class communicate with too many other classes:
Instead, limit the amount and direction of information exchange between classes and create larger architectures from the following building blocks:
You may have many classes but each class should communicate with as few others as possible. If any two classes communicate at all, they should exchange as little information as possible.
Each scope should reflect a single coherent level of abstraction that corresponds to its hierarchy level [ClCd]. In your UML, abstraction should decrease from top to bottom. In your code, the deeper you are in a call tree, the more specific your instructions can be. Avoid state variables at high abstraction levels.
| Bad ❌ | Better ✔ | Better ✔ |
engine.start()
nStartUps += 1
if fuelTank.isEmpty():
fuelGaugeUI.setRedLED() |
engine.start()
engine.runTest()
warnings = engine.warnings()
dashboard.show( warnings ) |
sys.test():
engine.test():
sparkPlug.test():
testIgnition() |
⚠ Caution: Mixing abstraction levels creates confusion and introduces unnecessary dependencies.
Once you have an initial plan for the architecture, you can start writing the code for classes and subprograms.
Any piece of data or logic should have a single source. Duplicated code is difficult to maintain and represents a missed opportunity for abstraction. As a rule of thumb: If you repeat more than 2 statements more than 2 times, write a new subprogram. At best, any atomic change in program logic should only affect a single line of code.
There are two code smells that should remind you of this rule:
-
Copy & Paste: Every time you take your mouse and mark lines with the intention to copy them, you are going to violate this rule. Instead of slightly adjusting copied lines, think about the common pattern between those lines and create a new function.
-
Repeated
if-elseandswitch-casestatements: If you are testing the same conditions at different locations (e.g. state variables), you can abstract these differences with Polymorphism and the Strategy Pattern.
Define subprograms and variables in the smallest scope possible and limit their exposure to external code. Put declarations at the beginning of each scope and initialize variables directly at the declaration. Do not reuse variables in nested scopes or for different purposes.
Avoid magic numbers (literal numbers with unclear origin/purpose) but always create constants with meaningful names. Create new types or derive subtypes from primitives to create more specific names, especially for physical quantities.
Bad ❌
double limit = 13.89; // unit not clear
from_to(int x, int y,
int x2, int y2); // vague argument names
if (speed > limit &&
t.h > 22 && t.h < 6){ ... } // 22 and 6 are magic numbersBetter ✔
MeterPerSecond limit = SPEED_LIMIT_NIGHT;
drive(Point origin, Point destination);
isNight = (T_NIGHT_MIN < t.h && t.h < T_NIGHT_MAX);
isSpeeding = (limit < speed);
if (isSpeeding && isNight){ ... }If the argument list of a subprogram grows too long, try to combine related arguments in a
new data structure. For example, instead of passing x, y, z
coordinates individually, use a single vector.
| Bad ❌ | Better ✔ |
makeCircle(double r, double x, double y) |
makeCircle(Point center, double radius) |
Within a subprogram, do not modify the same variable in several steps,
e.g. by summing up an amount using total += ... multiple times.
Instead, call functions that return some part of the final value and
then compose the final value of these parts in one instruction at the
end. E.g. total = partA + partB.
| Bad ❌ | Better ✔ |
totalIncome = 0
// ... long code to get contract
totalIncome += contract.salary
// ... long code to access taxoffice
totalIncome -= taxoffice[id].tax |
Int totalIncome(employee){
salary = getSalary(employee)
tax = getTax(employee)
return (salary - tax)
} |
Code should communicate behavior to other humans with lower complexity than the behavior it inherits. Since code mostly consists of custom names, your ability to abstract concepts with meaningful names is most important for readability.
Each concept should be described by a single word. Do not use send(), write(), and transmit() as synonyms for the same process, such as sending a message over a bus. Same holds true for handleRequest(), processQuery(), or manageIncomingPacket().
Each word should only describe a single concept. Do not use activate() for setting a boolean variable and sending an activation packet to another system component. The first procedure is safe and instant, the second could fail, block execution, or run asynchronously. Better call it sendActivationMsg().
Clean code reads like prose and these prefixes achieve clear and concise naming.
There is no difference between the naming of variables, e.g. hasElements, and functions, e.g. hasElements(), except that functions can also answer true/false questions regarding arguments, such as isFile(path) or user.hasAccessTo(file).
- consider the slightly uncommon prefixes
canto express abilities/possibilities, e.g.canWalk. - boolean names regarding Collections should use
Each/Anybefore the prefix, e.g.isEachLightOn/isAnyLightOn - prefer positive forms. Use
isActivenotisInactiveto avoid confusing negations (!isInactive). Same forhasElements(notisEmpty) andisEnabled(notisDisabled). - Avoid further uncommon prefixes, such as
does,are,was,will,should.
| Rule | Bad ❌ | Better ✔ |
|---|---|---|
Consider can |
isAllowedToWalk, hasWalkAbility, isWalkable |
canWalk |
Avoid not |
isNotEmpty, !isEmpty |
hasElements |
Avoid are: |
areAllLightsOn, isAllLightsOn , allLightsOn |
isEachLightOn |
Avoid was/had |
wasSend, hasBeenSent, hadArrived |
isSent |
Avoid does |
doesUseIO, mightUseIO |
isUsingIO, canUseIO |
Fun fact: The old jQuery 1.7 had a boolean called doesNotAddBorder. Now they use isBorderBox.
Procedures may return values, functions always return a value. Methods are subprograms of a class.
- procedure names should start with a verb. e.g.
syncViews(),list.addItem(x). - function names should describe the result and, if suitable, its type. e.g.
time_ms(), sin(x), isFile(path) - class methods should not repeat or include the name of the class. Define
Line.length(), notLine.getLineLength()
⚠ Caution: Single noun subprograms should be pure functions! Never let e.g.
x.length()change a state.
- type names should be capitalized nouns. E.g.
Integer,Date,Line2D - enums/structs are types and should be named as types without a special prefix/suffix.
E.g.enum Color = {RED, GREEN, BLUE} - interface names can start with a capital
Iand can also be adjectives. E.g.IObservable
- variables with a large scope should have long names, variables with a small scope may have short names [CdCm].
- collections (set, array, dict) should have a plural name. E.g.
cars,indices - the prefix
nornumshould be used for names representing the total number of objects in a collection. E.g.numCars - write constant names in capitals. E.g
CFG_TEMPERATURE_MAX = 80.0 - prefix global variables with
g_
| Bad ❌ | Better ✔ |
score_list = [0] * scores
for idx, val in score_list:
score_list = val + 1 |
scores = [0] * numScores
for idx, score in scores:
scores[idx] = score + 1 |
If you start something, you should stop it and not end it [CdCm].
While most opposites can be created by using un- or de- prefixes (lock/unlock), some are more distinct and allow code alignment:
Verb pairs with same length:
set |
send |
query |
insert |
attach |
show |
split |
enter |
accept |
|---|---|---|---|---|---|---|---|---|
get |
recv |
reply |
delete |
detach |
hide |
merge |
leave |
reject |
👆 List of further word pairs
Verb pairs that differ by one character are more visually distinct but still easy to align with one extra space:
open |
read |
load |
push |
start |
create |
grant |
hit |
prepend |
empty |
|---|---|---|---|---|---|---|---|---|---|
close |
write |
store |
pop |
stop |
destroy |
deny |
miss |
append |
full |
Noun and adjective pairs with same/similar length:
max |
next |
head |
new |
row |
ack |
front |
source |
client |
primary |
leader |
|---|---|---|---|---|---|---|---|---|---|---|
min |
prev |
tail |
old |
col |
nak |
rear |
target |
server |
replica |
follower |
⚠ Avoid inappropriate terms: Many organizations discourage the use of
master/slavedue to their negative association in different cultures. See 1 and 2.
⚠ Avoid useless noise-terms: E.g.data,info,process. What would be the difference betweenProduct,ProductData, andProductInfo?
A clear and consistent visual appearance of your code improves readability and readability helps to understand the code.
- Existing Project: Stick to the existing recommendations and tools.
- New Project: Use an automatic code formatter. Examples:
| Language | Tool |
|---|---|
| Python | black |
| C | uncrustify |
| C++ | clang-format |
| JavaScript | prettier.io |
👆 Read more ...
Here are some example recommendations that would be ensured by most formatters:
- aim for one statement and less than 80 characters per line
- indent with spaces not tabs because editors do not agree on tab width
- surround top-level function and class definitions with two or three blank lines.
- surround binary operators (=, ==, +) with a single space, except when nested inline
- break lines before operators and align operators vertically
English is the language of programming, so documentation should also be in English.
Choose your words carefully and comment only what the code cannot say, that is why you did it, maybe what you did, but never how. Change comments when code changes because “comments that contradict the code are worse than no comments” [PEP8].
| Bad ❌ | Better ✔ |
if t.h > NIGHT_H: # Check if night
if ifr.sense(): # detect person
turnLightOn() # set Pin 13
lockLight(TIMEOUT) # TIMEOUT=5s |
if (isNightTime() and isPersonPresent()):
turnLightOn()
lockLight(TIMEOUT) # avoid flickering |
Further Don'ts:
- Don't commit commented-out code. Just remove.
- Don't create headings with
S E P A R A T E Dletters because you cannot search for them. - Don't assume insider knowledge but write simple comments for anybody on the planet.
- Don't make jokes or use cute language.
- Don't comment closing braces. They just indicate that your blocks are too long.
Comment unfinished work with TODO: or FIXME:, which allows to search & find these lines later. Some IDEs will automatically highlight these tags via extensions.
A TODO is more urgent and needs to be done, a FIXME would be nice to have but is not required.
There are two different interest groups for your code, so please make sure that your Readme addresses both.
- Users: How to install and run your code with examples. Supported OS. Release versions and change logs.
- Developers: How to compile. Module structure, dependencies, contribution rules, where to contact developers.
| Level | Use-case | Example |
|---|---|---|
| Fatal: | the system cannot continue operation | segfault |
| Error: | some function is (currently) not working | no connection |
| Warn: | unexpected event but retry/alternative works | dropped packet |
| Notice: | notable events that do not happen often | new device |
| Info: | usual business events relevant to the user | user connected |
| Debug: | technological info relevant for developers | protocol stages |
| Trace: | step-by-step implementation details | loop index |
- Each log entry should at least output log level and file/module name (or topic label). Timestamps and line numbers are optional.
- Log with context and avoid messages like “Operation Failed” or “Write Complete”.
- Separate message (
"User connected") from parameters ("ip=%s", ip)
Bad ❌
print("User %s connected from %s", uid, ip)Better ✔
log.info("P2P: User connected. [id=%s, ip=%s]", uid, ip)Each code file with interfaces (e.g. .h files in C) should start with a block comment that briefly explains what this module/class/lib does. However, do not provide author name or changelogs as this info belongs into the Version Control System.
Docstrings are specially formatted comments that can be converted into a code documentation. This is useful as soon as other people start to depend on your interfaces.
👆 Docstring Example
/**
* Solves equations of the form a * x = b
* @example
* // returns 2
* globalNS.method(5, 10);
* @example
* // returns 3
* globalNS.method(5, 15);
* @returns {Number} Returns the value of x for the equation.
*/
globalNS.method = function (a, b) {
return b / a;
};
Each programming language has special mechanisms and some rules are only applicable to a certain language. We also try to give an overview of language-specific rules, but the following list is unfinished and work in progress.
This guide is partly based on the principles that are explained in the following books and documents and we can recommend them as further reading material.
Students from TUM and other universities can read these books for free. Simply click the links below and login with your university credentials.
- [CdCm] S. McConnell: “Code Complete”, Pearson Education, 2004.
- [ClCd] R. C. Martin: “Clean Code: A Handbook of Agile Software Craftsmanship”, Pearson Education, 2009.
- [ClAr] R. C. Martin: “Clean Architecture: Guide to Software Structure and Design”, Pearson Education, 2017.
- [HdFi] E. Freeman et al.: “Head First Design Patterns”, 2nd Edition, O’Reilly Media, 2020.
- [PEP8] G. Van Rossum, B. Warsaw, and N. Coghlan: “PEP 8: Style Guide for Python Code”, Python.org, 2001.
- [MISRA-C] Motor Industry Software Reliability Association: “Guidelines for the use of the C language in critical systems.”, 2004
- [MISRA-C++] Motor Industry Software Reliability Association: “Guidelines for the use of the C++ language in critical systems.”, 2008
- [JPL-C] JPL Institutional Coding Standard for the C Programming Language
- C++ coding style (JSF+MISRA):
- Google C++ Style Guide
- Google Python Style Guide