This document summarizes a presentation on clean code principles: 1. It outlines 9 main rules for writing clean code, including naming conventions, formatting for readability, using a single level of abstraction, single responsibility principle, and avoiding comments that repeat code. 2. An example task is used to demonstrate applying the rules when coding a solution. The presentation emphasizes naming things clearly, separating concerns into well-named functions, and avoiding "magic numbers." 3. Lastly, the presentation discusses balancing flexibility vs simplicity when coding generically for changing requirements, noting the most understandable solutions are often the best. Overall it promotes writing code that is easy to understand and maintain.

1. Clean Code
Knowledge Sharing Session 2020-01-24

2. An example:

3. An example:

4. Idea
Task:
● Find out the amount of labels each labeller created after the 1st of January
2019 that have an area of more than 100m²
Gather
labels from
Database
Filter labels
by date
Filter labels
by area
Aggregate
labels by editor
Print results

5. Clean code looks like
prose text.

6. Disclaimer
● I don’t follow all rules in this presentation myself
○ But it’s good to know them
● Business team:
○ Learn: What is “good” code, what is “bad” code?
○ Learn: The every day struggle of a programmer
● Tech team:
○ Learn: How to structure your code
○ Learn: Rules to keep in mind next time you code something!

7. Rule 1: Naming
● Name things in a way that perfectly describes what they are
○ Be clear
○ Be unambiguous
○ Use one name for one concept
■ Don’t mix words!
■ If you started calling it “Geometry”, stick to it! Don’t call it “Polygon” somewhere else!
○ Avoid abbreviations/acronyms
■ Lbls -> Labels (Its really only 2 letters more!)
■ Cx_hull -> Convex_hull

8. Rule 1: Naming
a. Be clear
b. Be unambiguous
c. Use one name for one
concept
d. Avoid
abbreviations/acronyms

9. Rule 1: Naming

10. Rule 2: Formatting
● Format for readability
○ Empty lines where helpful
○ Avoid too long lines
○ Follow existing style guides (For python: PEP8)

11. Rule 2: Formatting
○ Empty lines where helpful
○ Avoid too long lines
○ Follow existing style
guides (For python: PEP8)

12. Rule 2: Formatting

13. Rule 3: Single level of abstraction
● All things that happen in a code block should use the same level of
abstraction
○ Example:
■ Don’t create a DB connection and filter Polygons by area in the same function!
○ Real world example:
■ Don’t compute the friction of the wheel of a car and define which pedal has to be
pressed to accelerate
● Instead:
○ Split into well-named functions!

14. Rule 3: Single level of
abstraction
● A database connection is
created
○ WIth all unnecessary details such
as the host and the login data!
● A geometry is reprojected and
its area is calculated
● Labels are grouped by editor

15. Rule 3: Single level of
abstraction

16. Rule 4: Single responsibility principle
● Each function should have one clearly defined responsibility
○ Good naming is essential
■ If your name uses the word “and”, you failed.
● Also known as
○ A function should only ever have one reason to change

17. Rule 4: Single responsibility principle

18. Rule 4: Single responsibility principle

19. Rule 5: Code for change
● We live in a terrible world where requirements keep changing
○ Keep this in mind while coding!
● Don’t use “magic numbers”
● Never ever ever ever hard-code credentials!

22. Rule 6: Group semantic concepts
● And name that group well!
● Avoids having too many variables
○ ⇒ Brain overload
● Don’t be afraid to create classes / named tuples / structs / whatever helps you
group things
● Also helps keeping all information in one point

23. Rule 6: Group semantic concepts

24. Rule 6: Group semantic concepts

25. Rule 7: Avoid mental mapping
● Be explicit!
● Don’t try to “remember” things!
Totally forgot
what this is

26. Rule 7: Avoid mental mapping

27. Rule 8: Don’t try to be clever
● Don’t search for the most clever solution
● Search for the simplest solution
● We spend more time reading code than writing code!
○ Make sure it is very easy to understand!

28. Rule 8: Don’t try to be clever
Weird python
thing that tries to
be smart

29. Rule 8: Don’t try to be clever
If we don’t know
that editor, this
is his first label!

30. Rule 9: Comments
● Comments should explain WHY things are happening.
● The code should explain WHAT is happening.
Thanks for repeating that
Annoying comment
repeating the code
If your code block is so
complicated it needs a
caption, why not make it a
function?

31. Rule 9: Comments
● Comments should explain WHY things are happening.
● The code should explain WHAT is happening.
Oh! That looked like a typo.
Good thing we have that
comment!
Great! Now I know where to
start optimizing

32. Rules Summary:
1. Name things well
2. Format your files for readability
3. Keep a single level of abstraction
4. Every block should have a single responsibility
5. Code for change
6. Group semantic concepts
7. Avoid mental mapping
8. Don’t try to be clever
9. Comments should explain WHY things are happening!

33. Let’s look at our code!
[ Switch to IDE here]

34. Rules Summary:
1. Name things well
2. Format your files for readability
3. Keep a single level of abstraction
4. Every block should have a single responsibility
5. Code for change
6. Group semantic concepts
7. Avoid mental mapping
8. Don’t try to be clever
9. Comments should explain WHY things are happening!

35. Last Minute “We’re on our way to the meeting”-request
● “Quick! Don’t filter by 100m², but 1000m²!”
○ Easy

36. ● “Quick! Don’t filter by 100m², but 1000m²!”
○ Easy
Last Minute “We’re on our way to the meeting”-request
● “We just noticed that the labels of today are included! We don’t want them!”
○ Uhm, okay one second...

37. ● “Quick! Don’t filter by 100m², but 1000m²!”
○ Easy
● “We just noticed that the labels of today are included! We don’t want them!”
○ Uhm, okay one second...
Last Minute “We’re on our way to the meeting”-request
● “Hey, we found this CSV with labels, can you use that instead of the DB?
Oh, and can you group by modification date instead of editor? And give us a
CSV with the results please. We need to show this to the customer”
○ Ehm… No.

38. Idea
Task:
● Find out the amount of labels each labeller created after the 1st of January
2019 that have an area of more than 100m²
Gather
labels from
Database
Filter labels
by date
Filter labels
by area
Aggregate
labels by editor
Print results

39. Idea
New task:
● Take labels from somewhere, group them by some criteria and filter them by
some arbitrary filter and then print the results somewhere
Gather
labels from
somewhere
Filter labels
somehow
Aggregate
labels by some
criteria
Output the
results
somewhere

40. So...
● We make sure we can define arbitrary data sources
● We want to be able to define arbitrary filters
● We want to be able to specify arbitrary output destinations

41. Let’s look at our code!
[ Switch to IDE here]

42. But wait! Now it has gotten super complicated again!
● Solving the “generic” problem always makes the code complicated
● Our implementation is super flexible now, but harder to understand
● Ask yourself: Do we need this flexibility? Will requirements change that often?

43. KISS =
Keep It Simple, Stupid!

44. Be pragmatic!

45. Thanks for listening!