
## What does SOLID stand for?

**SOLID is a mnemonic acronym** of 5 acronyms themselves: **SRP** - Single Responsibility Principle, **OCP** - Open-Closed Principle, **LSP** - Liskov Substitution Principle, **
ISP** - Interface Segregation Principle, **DIP** - Dependency Inversion Principle.

These ideas were first mentioned by Robert C. Martin (Uncle Bob) in his
paper _"[Design Principles and Design Patterns](https://fi.ort.edu.uy/innovaportal/file/2032/1/design_principles.pdf)"_. Later, Michael C. Feathers coined the SOLID acronym, which
was then re-used by Uncle Bob in the chapter "_Design Principles_" in his book "Clean Architecture".

## Single Responsibility Principle (SRP)

> There should never be more than one reason for a class to change
>
> SRP: The Single Responsibility Principle - Robert C. Martin

The **single responsibility principle** was coined by Robert C. Martin himself but he also pays credit to Tom DeMarco's concept of cohesion, which he described
in "Structured Analysis and System Specification". It is the first of the SOLID principles and encourages to give classes only **a
single** and definite **reason to change**. If you can think of more than a single reason for the class to change, the class has more than one responsibility. SRP is often confused
with the ["Do one thing"-rule](https://code-specialist.com/blog/do-one-thing/) At a first glance, this concept seems rather abstract and useless, but the example that is
provided in the initial paper is kind of helpful:

![How to violate the Single Responsibility Principle. The Rectangle class has two reasons to change.](https://raw.githubusercontent.com/yannicschroeer/diagrams/3d65e422d6253dc0860b2809d13eb5cbac182247/srp_violation.svg)

Imagine a rectangle class that has the two public methods draw and area. The draw method should return coordinates or any graphical representation. The area method returns the area
of the current rectangle instance. The rectangle class thereby has two responsibilities. It's responsible for calculating the area and responsible to draw itself.

```python
class Rectangle(object):
 
  def __init__(self, height: float, width: float):
    self.height = height
    self.width = width
  
  def draw(self) -> VisualRepresentation:
    return visual_representation(self)
  
  def area()-> float:
    return self.height*self.width
```

If you are confused by the types behind the arguments in the constructor, you should have a look at [Python type hints](https://code-specialist.com/blog/type-hints/). However,
changes in the rectangle class would **affect** the GUI as well as the geometric calculation app. Changes in the rectangle class could potentially break the whole system or lead to
unpredictable bugs. The solution Martin proposes in this specific case is to split the class into two separate ones:

![Proposed solution to comply with the Single Responsibility Principle. A second class GeometricRectangle, implementing the math related methods](https://raw.githubusercontent.com/yannicschroeer/diagrams/46134d246c47b5564fd70f2f4d710a44f411888f/srp_solution.svg)

This separation leads to a **single responsibility** for each the geometric rectangle and the rectangle class. Changes in the draw method now can no longer affect the way they are
calculated.
```python
class GeometricRectangle(object):
  
  def __init__(self, height: float, width: float):
    self.height = height
    self.width = width
    
  def area()-> float:
    return height*width
  

class Rectangle(GeometricRectangle):
  
  def draw(self) -> VisualRepresentation:
    return visual_representation(self)
```

The attentive readers might have noticed that this concept's **strict and mindless usage will also lead to poor software design**. It would help if you never used the single
responsibility theory without proper support of other constructs like modules or facades. Otherwise, the structure proposed by the SRP will cause the code to break into a thousand
confusing pieces

## Open-Closed Principle (OCP)

> Software entities (classes, modules, functions, etc.) should be open for extension but closed for modification.
>
> The Open Closed Principle - Robert C. Martin

Whatever your personal definition of stable code is, this SOLID principle should be part of it. A good software architecture will almost certainly always fulfill the open-closed
rule. Originally, Bertrand Mayer coined this concept in his book "Object-Oriented Software Construction". OCP applies to all kinds of
objects in programming you can imagine. This philosophy's main focus is to allow you to scale your classes and modules without caring about legacy code. To simplify this, we are
just going to look at applying it to classes.

The key message of the **open-closed principle**, in this case, is that your classes should be open for extension but closed for modification. Meaning, once you created your class,
it **shouldn't change** any more. However, it could change by simply creating a child class that thereby **extends its behavior**. Imagine you had a user class that holds a name
and an age.

```python
class User:
  
  def __init__(self, username: str, age: int):
    self.username = username
    self.age = age
  
  def __repr__(self):
    return f"User: {self.username}, {self.age} years old"
```
Now imagine you want to extend this class by an attribute that saves the user's favorite game. A naive solution to this problem would be to simply add an attribute "favorite\_game"
to the user class:

```python
class User:

  def __init__(self, username: str, age: int, favorite_game: Game):
      self.username = username
      self.age = age
      self.favorite_game = favorite_game

  def __repr__(self):
      return f"User: {self.username}, {self.age} years old, favorite game: {self.favorite_game}"    
```


This might work if your system is small or in development. But if you want to change this in a productive system, things are going to break. Not only did the signature change
because the constructor now expects a favorite\_game, but also the _\_\_repr\_\__ method changed and might break things further. This violates Meyer's postulate. A possible
solution to this again could be inheritance:

```python
class User:

  def __init__(self, username: str, age: int):
      self.username = username
      self.age = age

  def __repr__(self):
      return f"User: {self.username}, {self.age} years old"


class Gamer(User):

  def __init__(self, username: str, age: int, favorite_game: Game):
      super().__init__(username, age)
      self.favorite_game = favorite_game
      
  def __repr__(self):
    return f"User: {self.username}, {self.age} years old, favorite game: {self.favorite_game}"     
```

By using this, your **functionality is extended**, but you don't apply any changes to the original class. _Please note: Inheritance isn't always a good solution or a solution at
all, but it is the easiest example to make._ _SOLID is not directly related to inheritance or polymorphism._

## Liskov Substitution Principle (LSP)

> _Subtype Requirement_: Let _**φ(x)**_ be a property provable about objects **_x_** of type _**T**_. Then **_φ(y)_** should be true for objects **_y_** of type **_S_** where _**S**_ is a subtype of _**T**_.
>
> A behavioral notion of subtyping - Barbara Liskov and Jeanette Wing

When you are most familiar with Python or hate maths, the **Liskov substitution principle** might be slightly confusing. This is because it originally was designed for **statically
typed programming languages** like Java, C, or FORTRAN. [Barbara Liskov](http://www.pmg.csail.mit.edu/~liskov/) introduced it in 1987. It is often considered the hardest of the
SOLID principles to understand. Visualizing Liskov's definition leads to the following class diagram:

![Liskov Substistion Principle definition as an UML class diagram](https://raw.githubusercontent.com/yannicschroeer/diagrams/64e744c8f9f3b7f04c9cf5f2cd81c0cd754816d8/liskov.svg)

We have a type **_T_** and a subtype _**S**_, and objects of _**x**_ that are of type **_T_** and objects _**y**_ of type _**S**_. Also, all the elements posses an attribute **_φ_**.
A representation in Python code could look like this:

```python
class T:
  
  def __init__(self, phi: list):
    self.phi = phi
    
class S(T):
  pass

if __name__ == "__main__":
  x = T(phi=["a", "b"])
  y = S(phi=["c", "d"])
```

And this indeed fulfills the Liskov substitution principle. Any object of type _**S**_ could replace its parent class. How could you possibly violate this?

```python
class T:
  
  def __init__(self, phi: list):
    self.phi = phi
    
class S(T):
  
  def __init__(self, phi: str):
    self.phi = phi

if __name__ == "__main__":
  x = T(phi=["a", "b"])
  y = S(phi="c, d")
```

If you look closely, you will see that the subtype S implements its own class attribute phi of type string instead of list. This violates Liskov's theory. You can no longer
replace _**T**_ with objects of type _**S**_. One becomes aware of this concept's meaningfulness when you think about implementing a method "_print\_phis_" that should solely print
all elements in the class attribute phi. Either instances of class _**T**_ or _**S**_ would run into a runtime error or lead to a higher degree of complexity in the "_print\_phis_"
method due to additional conditionals.

## Interface Segregation Principle (ISP)

> Clients should not be forced to depend upon interfaces that they do not use.
>
> The Interface Segregation Principle - Robert C. Martin

ISP or **interface segregation principle** is the SOLID equivalent of **high cohesion**
in [GRASP (General Responsibility Assignment Software Principles)](/grasp/). Thereby it naturally supports loose coupling and
maintainability. The main message behind ISP is that large Interfaces should be split into multiple ones. Functions and classes should not depend on methods they don't use. Look at
the following example for a "fat" interface:

```python
class GeometricInterface(ABC):
  
  @abstractmethod
  def get_area() -> float:
    raise NotImplementedError
    
  @abstractmethod
  def get_diameter() -> float:
    raise NotImplementedError
    
class Square(GeometricInterface):
  
  def __init__(self, height: float, width: float):
    self.height = height
    self.width = width
  
  def get_area():
    return self.height*self.width
  
  def get_diameter() -> float:
    raise NotImplementedError
  
class Circle(GeometricInterface):
  
  def __init__(self, radius: float):
    self.radius = radius
  
  def get_area():
    return self.radius * PI **2
  
  def get_diameter() -> float:
    return self.radius*2
```

Please excuse the far-fetched example, nothing I'm proud of. However, as you can see, the GeometricInterface has two abstract methods of which `get_diameter()` is not used by
its subtype square. Thereby the interface segregation rule is violated. There are many possible solutions to this. We could, for instance, segregate the GeometricInterface into
three Interfaces:

```python
class GeometricInterface(ABC):
  
  @abstractmethod
  def get_area() -> float:
    raise NotImplementedError

class ElipseInterface(GeometricInterface, ABC):
  
  @abstractmethod
  def get_diameter() -> float:
    raise NotImplementedError

class RectangleInterface(GeometricInterface, ABC):
  pass


class Square(Rectangle):

    def __init__(self, height: float, width: float):
        self.height = height
        self.width = width

    def get_area(self):
        return self.height * self.width

class Circle(Elipse):

    def __init__(self, radius: float):
        self.radius = radius

    def get_area(self):
        return self.radius * PI ** 2

    def get_diameter(self) -> float:
        return self.radius * 2
```

## Dependency Inversion Principle (DIP)

> A: High level modules should not depend upon low level Modules. Both should depend upon abstractions.
>
> B: Abstractions should not depend upon details. Details should depend upon abstractions.
>
> The Dependency Inversion Principle - Robert C. Martin

In my opinion, the **dependency inversion principle** is the easiest one to understand. However, it can be the hardest to implement. In essence, the DIP states that modules should
not rely on modules that belong to a subordinate concept and should not rely on generalizations. A quick piece of code that is often referenced:

```python
class LightBulb:
  
  def __init__(self, initial_state: bool=False):
    self.power = initial_state
    
  def turn_on(self):
    self.power = True
    
  def turn_off(self):
    self.power = False

class Switch:
  
  def __init__(self, light_bulb: LightBulb, pressed: bool=False):
    self.light_bulb = light_bulb
    self.pressed = pressed
    
  def toggle(self):
    self.pressed = not self.pressed # Toggle
    if self.pressed:
      self.light_bulb.turn_on()
    else:
      self.light_bulb.turn_off()
```

The **DIP violation** here is that a switch is a concept that is logically in a layer above the light bulb, and the switch relies on it. This will lead to poor extensibility or
even circular imports that prevent the program from being interpreted or compiled.

![Violating the Dependency Inversion Principle. The controller module relies on the device module instead vice versa](https://raw.githubusercontent.com/yannicschroeer/diagrams/fe1c96e84d8ef0701c95399a796805d6c938cf46/dip_violation.svg)

Instead of the light bulb telling the switch how the bulb should be handled, the switch should tell the light bulb how to implement it. The naive approach would be to define an
interface that tells the light bulb how it should behave to be used with a switch.

```python
class Device(ABC):
  power: boolean
    
  def __init__(self, initial_state: bool=False):
    self.power = initial_state
    
  def turn_on(self):
    raise NotImplementedError
  
  def turn_off(self):
    raise NotImplementedError
    
class Switch:
  
  def __init__(self, device: Device, pressed: bool=False):
    self.device = device
    self.pressed = pressed
    
  def toggle(self):
    self.pressed = not self.pressed # Toggle
    if self.pressed:
      self.device.turn_on()
    else:
      self.device.turn_off()  

class LightBulb(Device):
  
  def turn_on(self):
    self.power = True
    
  def turn_off(self):
    self.power = False
```

Visualized as a class diagram, this source code would lead to the object-oriented design:

![Dependency Inversion Principle in an UML class diagram. A Device Interface as the solution for the switch not to rely on the light bulb](https://raw.githubusercontent.com/yannicschroeer/diagrams/14b34110edd15e8d5325a5e28c8e61ca91df3670/dip_solution.svg)

**The dependency has been inverted**. Instead of the switch relying on the light bulb, the light bulb now relies on an interface in a higher module. Also, both rely on
abstractions, as required by the **DIP**. Last but not least, we also fulfilled the requirement "Abstractions should not depend upon details. Details should depend upon
abstractions" - The details of how the device behaves rely on the abstraction (Device interface).

## Conclusion

As with all guidelines, it's not recommended to follow the SOLID principles blindly either. Principles, patterns, and guidelines can easily turn into anti-patterns and lead to new
problems. Sometimes it not preventable to violation some of these. Our job as a developer is to create code and programs that
are [easy to read and thereby easy to maintain and extend](https://code-specialist.com/code-principles/kiss-principle/). Robustness and correctness are more or less nice side
effects of this approach. These are great guidelines, but that's what they are, guidelines. Specific problems need specific solutions. All principles and patterns can offer are
suggestions and best practices.

If you support my statement or are of a completely different opinion I would love to hear about it in the comments section.

## References

- [SRP: The Single Responsibility Principle - objectmentor.com, 02.02.2015](https://web.archive.org/web/20150202200348/http://www.objectmentor.com/resources/articles/srp.pdf)
- [The Open-Closed Principle - objectmentor.com, 02.02.2015](https://web.archive.org/web/20150212141727/http://www.objectmentor.com:80/resources/articles/ocp.pdf)
- [The Liskov Substitution Principle - objectmentor.com 11.02.2015](https://web.archive.org/web/20150211000751/http://www.objectmentor.com/resources/articles/lsp.pdf)
- [The Interface Segregation Principle - objectmentor.com 10.02.2015](https://web.archive.org/web/20150210224002/http://www.objectmentor.com/resources/articles/isp.pdf)
- [The Dependency Inversion Principle: objectmentor.com 10.02.2015](https://web.archive.org/web/20150210213530/http://www.objectmentor.com/resources/articles/dip.pdf)
- [Design Principles and Design Patterns](https://cds.cern.ch/record/1419478/files/0135974445_TOC.pdf)
- [Barbara Liskov, Professor at MIT](http://www.pmg.csail.mit.edu/~liskov/)
- [GRASP: General Responsibility Assignment Software Principles, code-specialist.com](https://code-specialist.com/blog/grasp/)
- [KISS Principle code-specialist.com](https://code-specialist.com/blog/kiss-principle/)
- [Do one things, code-specialist.com](https://code-specialist.com/blog/do-one-thing/)
- [Python type hints, code-specialist.com](https://code-specialist.com/python-type-hints/)

SOLID Principles with Python Code Examples


## About GRASP

This collection of **object-oriented design rules** goes back to **Craig
Larman** and his book **Applying UML and Patterns** from 2004. Larman didn't
invent any of these principles and ideas. He simply collected them.

**GRASP** is a pretty fancy name, but it somehow feels more like he wanted GRASP
as the acronym and linked random words to reach it. Even though it is about to
become an oldie, most rules collected under the GRASP banner are still helpful,
and they should be essential to every developer's toolkit.

The **General Responsibility Assignment Software Principles** list nine
principles:

1. Controller
2. Creator
3. Indirection
4. Information Expert
5. Low Coupling
6. High Cohesion
7. Polymorphism
8. Protected Variations
9. Pure Fabrication.

Though they are tailored to object-oriented design, some also apply for general
software development as well.

I write about some things that are not from Larman's book but my own opinion and
personal note. If you don't want the unaltered version, I suggest you read the
original book: _Applying UML and Patterns: An Introduction to Object-Oriented
Analysis and Design and Iterative Development_

## Controller

The controller pattern is a common tool in object-oriented software design.
Though most people might only associate the controller with the ancient
architecture of the MVC (Model-View-Controller - Which is far too often used for
cases it absolutely doesn't fit, but that's a story for a different day), the
controller is a construct of itself.

As the name implies, the controller's work is to 'control' any events that are
not directly related to the user interface. But controlling does not mean
implementing. The controller consists of barely any logic. It is merely a
mediator between the presentation layer and the (core) logic.

For example, if we imagine a simple web-shop application with the use case of
"User X bought item A"; The controller's job would be to receive the signal of
the pressed button from the UI and then run the necessary functions in the
correct order. In the example at hand that could be to certify the payment and
then initialize the shipment of the item.

Applying the principle of a controller can hugely improve your software's
lifetime as it naturally creates a resilient layer regarding the
interchangeability of code. If your UI or logic (unlikely, but possible), you
can adjust your mappings instead of having to rewrite large chunks of code.

Also, it becomes incredibly easier to add other layers, such as an app at the
overlaying presentation layer that uses a different UI but wants the same
responses.

You can also think of a controller as a driver. It knows both parts it connects
with one another but it acts merely as a broker. It consists of just a few and
essential parts of code.

## Creator

The creator is another pattern, but to me, it's more like an abstract idea than
a real pattern. I must admit I rarely use this pattern intentionally.

A creator is a class that is responsible for creating instances of objects.
Larman defines the following cases as _B is the creator of A_:

- B _aggregates_ A objects
- B _contains_ A objects
- B _records_ instances of A objects
- B _closely uses_ A Objects
- B _has the initializing_ data that will be passed to A when it is created

So an example for a creator could be a library that _contains_ books. In that
case, the library would be the creator of books, even though this sounds
syntactically weird as natural language.

## Indirection

Indirection isn't a pattern but an idea. It is also of no use of its own, only
in combination with other ideas such as low coupling. The goal behind
indirection is to avoid direct coupling.

To pick up an earlier example the controller for example is a kind of
indirection between the UI and the logic. Instead of coupling the UI directly to
the logic, the controller decouples this layer and thereby comes with all the
advantages of indirection.

## Information Expert

Another principle that falls into that area is the information expert. Sometimes
it is just called the expert or the expert principle. The problem that should be
solved with the information expert is the delegation of responsibilities. The
information expert is a class that contains all the information necessary to
decide where responsibilities should be delegated to.

You identify the information expert by analyzing which information is required
to fulfill a certain job and determining where the most of this information is
stored.

## Low Coupling

Low or loose coupling is the idea of creating very few links between modules. In
GRASP it is an inter-module concept. Meaning it describes the flow between
different modules, not the flow inside the modules.

Together with cohesion, it is the main reason upon which you make global design
decisions such as "Where do we pack this module or function to?".

Low coupling is another concept that supports interchangeability. By making very
few dependencies, very few code must be changed in case of a change.

## High Cohesion

in GRASP high (functional) cohesion is an intra-module concept. Meaning it
describes the flow inside a certain module not the flow between modules.

The main reason behind high cohesion is the idea of reducing complexity. Instead
of building large classes that have many functions that have few in common and
are hard to maintain, the goal should be to create classes that fit exactly
their defined purpose.

It's kind of hard to understand these abstract ideas but I also wasn't able to
come up with a simple example, which is why I will write an extra article on the
topic of low cohesion combined with high cohesion that is more detailed.

## Polymorphism

Polymorphism: `πολυ` (_polús_)= many/multi, `μορφή` (_morphé_) = shape/form,
`ισμός` (_ismós_) = imitation of.

Meaning, Polymorphism could be frankly translated as "something that imitates
many forms". And that might be a concise but useless explanation to someone who
has never heard of polymorphism.

Anyone who ever took a programming class is most likely familiar with
polymorphism. But, it can be a tricky question to define it sensefully.

The idea again is to reduce complexity by imagining that objects follow simple
and similar rules. Consider the following example: You have three objects A, B
and C. B has the same methods and attributes but has an additional method X. C
has the same methods and attributes as B, but an additional method Y.

The non-developer approach to this problem would be: "Great, as you said, we
have 3 objects, so we have A, B, and C. Problem solved. You little stinky
moron.". Yes, non-developers are insanely evil creatures.

![Three objects without polymorphism](/assets/blog/posts/grasp/polymorphism_wrong.svg)

```python
class A:
    attribute_a: str
    attribute_b: int
    attribute_c: float

    def being_useless(self):
        print("I am being of no use.")


class B:
    attribute_a: str
    attribute_b: int
    attribute_c: float

    def being_useless(self):
        print("I am being of no use.")

    def X(self):
        print("I am Batman.")


class C:
    attribute_a: str
    attribute_b: int
    attribute_c: float

    def being_useless(self):
        print("I am being of no use.")

    def X(self):
        print("I am Batman.")

    def Y(self):
        print("I am expensive to my parents.")
```

But as a programmer, you instinctively know that we need the concept of
inheritance here. A is an object, B is an object that inherits from A, and C is
an object that inherits from B. **Caution: Inheritance is not polymorphism** -
inheritance is an application that is allowed due to polymorphism.

![Simple polymorphism example - Venn
diagram](/assets/blog/posts/grasp/polymorphism_correct.svg)

```python
class A:
    attribute_a: str
    attribute_b: int
    attribute_c: float

    def being_useless(self):
        print("I am being of no use.")


class B(A):

    def X(self):
        print("I am Batman.")


class C(B):

    def Y(self):
        print("I am expensive to my parents.")
```

To wrap it up: polymorphism is the concept of disassembling objects and ideas
into their most atomic elements and abstracting their commonalities to build
objects that can act like they were others. Not only to reduce complexity but
also to avoid repetitions.

## Protected Variations

The protected variations pattern is a pattern used to create a stable
environment around an unstable problem. You wrap the functionality of a certain
element (class, interfaces, whatever) with an interface to then create multiple
implementations by using the concept of polymorphism. Thereby you are able to
catch specific instabilities with specific handlers.

An example of the protected variations pattern is working with sensory data,
such as a DHT22, a common temperature and humidity sensor often used for
Raspberry Pi or Arduino). The sensor is doing its job pretty well, but sometimes
it will say the temperature just rose by 200 celsius or won't return any data at
all. These are cases you should catch using the protected variations pattern to
avoid false behavior of your program.

## Pure Fabrication

To reach low coupling and high cohesion, it is sometimes necessary to have pure
fabrication code and classes. What is meant by that is that this is code that
does not solve a certain real-world problem besides ensuring low coupling and
high cohesion. This is often achieved by using factor classes.

## Some last words

Often when I look into programming principles, I feel mildly overwhelmed and
discouraged. That's in part because some of these concepts are very hard to
**grasp** if you never heard of them or got no practical use case in mind. But
with a growing set of programming principles and best practices, you will see
that all these principles refer to the same key statements and follow the same
rules.

Unfortunately, in my opinion, there's also no substitution for learning it the
hard way. Memorizing merely the key statements will eventually lead to greater
school and university scores, but it will still be useless incoherent
information without any practical use. Thereby, my advice is to learn as much as
possible about code and its principles but also get as much hands-on experience
as possible to abstract the key statements by yourself.

If you liked this post or are of any different opinion regarding any of the
written, please let us know via mail or comment. Happy coding!


GRASP - General Responsibility Assignment Software Principles


## Why are good names so important?

Every name you write in your code is only for humans. The compiler, interpreter or whatever component runs your code
will throw your names away and use internal identifiers. So the purpose of your names is literally just for you and
every other developer to understand the code. Furthermore, code is far more often read than written.

> Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as
> part of the effort to write new code.
> 
> **Robert C. Martin,** Clean Code: A Handbook of Agile Software Craftsmanship

Consequently, writing readable code by using meaningful names is much more rewarding than just doing it "quick and
dirty". It may take a lot longer than doing it quickly, but in the long term you and your colleagues will benefit from
the code quality.

## Giving bad names is quick

Even if it doesn't seem like it at first glance, sometimes it can be really difficult to give meaningful names. It is
often very challenging, especially to make it understandable for outsiders.

Everybody knows the situation, where you have a topic or a goal, and just start coding right away. You are incredibly
productive in a short time and the outcome is great. But most of the code we write in this attitude is anything but
clean and readable. Consider this small example where the names don't say anything about what the code does.

```python
def statistics_page_7():
    inp = get_data("sales")
    inp = clean_data(inp)
    inp = inp[::-1]
    av = sum(inp) / len(inp)
    sum_ = sum([pow(num - av, 2) for num in inp])
    res = math.sqrt(sum_ / len(inp))
    return get_page("Statistics", 7, res).render().get_content()
```

It is very hard to understand what the code actually does. The writer, with all the thoughts and concepts in mind,
will understand the code because he wrote it. But after a while, when not dealing with the code for a long time, those
insights are gone and the code isn't easily understandable anymore. Furthermore, when the code needs to be adjusted
because the requirements changed or there is a bug in it, there's a problem. Getting familiar with poorly written code
can be very frustrating and may take a long time. To fully understand the code, the developer possibly needs to debug
and dig into it line by line, which is really time-consuming and exhausting.

## How to give meaningful names

So, how can you come up with meaningful names? Here are a few tricks that will help you to improve the names in your
code!

### 1. Don't be afraid to use long names

Even if it seems confusing at the fist moment, long names are mostly better than short ones. Especially when the
shorter name would hide some relevant information, the better choice is always better to include it in the name.
The code will grow, but most information about purpose of the code is in the names. By the way, explaining what
the code does with lots of comments isn't a good idea, as you can see in our post
to [Comments - What you should keep in mind](https://code-specialist.com/write-better-code/comments/).

### 2. Keep your functions doing only one thing

By applying this principle, you keep your functions small and reusable. Every function has only one purpose, and
therefore it is easy to give them meaningful names. Additionally, you will have more functions and more
opportunities to give names. As a result, your code contains more names and tells what it's doing.

### 3. Let others review your code

Only if someone else understands your code you should be satisfied with the code and your names. There are lots of
other advantages of code reviews, so it's recommended to do it anyway. Nonetheless, after your code passed the
review, it's not "finished". Writing code is an iterative process that never ends, so you should keep improving it!

With these tricks and some creativity, we can refactor the previous code.

```python
def get_sales_statistics_page() -> str:
    sales_data: List[float] = get_data(sales)
    cleaned_sales_data: List[float] = clean_data(sales)
    sales_standard_deviation: float = calculate_standard_deviation(cleaned_sales_data)
    return get_html_page(topic="Statistics", page_id=7, template_data=sales_standard_deviation)

def calculate_standard_deviation(numbers: List[float]) -> float:
    variance = calculate_variance(numbers)
    return math.sqrt(variance)

def calculate_variance(numbers: List[float]) -> float:
    average = calculate_average(numbers)
    sum_of_squared_difference_from_average = 0

    for number in numbers:
        difference_from_average = number - average
        sum_of_squared_difference_from_average += pow(difference_from_average, 2)

    return sum_of_squared_difference_from_average / len(numbers)

def calculate_average(numbers: List[float]) -> float:
    return sum(numbers) / len(numbers)

def get_html_page(topic: str, page_id: int, template_data: dict) -> str:
    page_object = get_page(topic=topic, page_id=page_id, template_data=template_data)
    rendered_page = page_object.render()
    return rendered_page.get_content()
```

After this revision, the code grew a lot but it looks much more inviting. Other developers looking at this code will
more likely be motivated to read, understand and extend it.

I hope this post inspired you to reflect the namings in your code and improve the readability. Do you have any tips and
best practices for giving meaningful names in code? You're welcome to share and discuss them in the comments!


Meaningful Names


## Do we really need comments?

Nowadays, everyone uses source code management systems (like [GitHub](https://github.com/) for instance), 
especially when working with multiple developers on one project. If you don't use a code management system 
for your projects, consider migrating your project to use one. Even if you work alone on your project - 
it's still very useful.

With source code management systems, you can find every written line in the project. It doesn't matter if 
someone deleted it a long time ago, you can always look up every older version. So you don't need to 
comment-out code segments any more! Furthermore, when you have commented-out code in your project, it's 
very likely for it to remain for a long time. And someday you ask yourself: What is this code and why is 
it here? Maybe you don't even dare to delete it, because it could be from someone else and still relevant. 
In the end, it's always better to instantly delete unused code.

Okay, to comment-out code isn't a good idea. But it's still very useful to describe the code with comments, 
so other ones can understand it better, right? No, not in most cases. If you need to explain in every line 
what your code does, it's just not readable. There are so many ways to structure and style your code so it
becomes more readable. Consider this example, where you only have a chance to understand what's going on by 
reading the comments:

```python
def get_customer_data(csv):
    d = open(csv, 'r').readlines()  # read csv file as list with rows as strings
    cust_d = list()  # list of customer data which gets returned
    for i in range(1, len(d)):  # iterate over rows of csv file
        e = (d[0].split(';'), d[i].split(";"))  # split columns and rows to lists
        f = []  # helper array for better datastructure
        for n in range(len(e[0])):
            # add pairs of column name and value to helper array
            f.append([e[0][n], e[1][n]])
        # create dict with columns as keys and data as values for each customer
        cust_d.append({x.strip(): y for x, y in f})
    return cust_d
```

This code actually works with semicolon-separated CSV files, but it's really hard to read. So how can we 
improve this little mess?

## How to let your code speak for itself

There are a few ways to let your code tell what it's doing. The goal is that the person reading your code can 
easily understand what's going on, just by reading the actual code - and not any comments.

1. **Use meaningful names**
    
    Every programmer probably has already heard this advice somewhere. And few programmers will say: "Ah, 
    nothing easier than that! My names are always understandable, it's no hard deal". I think most of the
     people who said that (and I'm including me too) wouldn't understand some code they have written a few 
     years ago in some old project because it can be really hard to give meaningful names an outsider would 
     understand.
    
2. **Don't get too big**
    
    Especially in large and complex projects with thousands of lines of code, there are often situations where 
    functions, classes, etc. get really big. This causes various problems: On the one hand, it's just hard to 
    read and keep the context in mind when you have to scroll down a few times for reading one function. On the 
    other hand, giving meaningful names is much easier when you separate your code into different parts which 
    you can give describing names.
    
3. **Abstractions are your friends**
    
    This point goes hand in hand with the previous ones. Try to abstract everything you do. By using abstractions, 
    you have lots of opportunities to give explaining names for the different abstraction levels. Additionally, 
    you prevent your functions, classes, etc. to get too big. The idea of this approach is to hide further details 
    behind every abstraction, and every time you dive deeper, you get to see more detail. Mostly it isn't necessary 
    to know the details from another point of view, and it's way easier to understand the code's purpose from a 
    high-level perspective.

With these concepts in mind, we can refactor the previous code example a bit. After doing that, it looks like this:

```python
from typing import Dict, List

def extract_values_from_string(string: str) -> List[str]:
    cleaned_string = string.strip()
    string_as_list = cleaned_string.split(";")
    return string_as_list


def map_columns_to_values(column_names: str, rows: List[str]) -> List[Dict[str, str]]:
    column_value_mappings = list()
    column_names_list = extract_values_from_string(column_names)

    for row in rows:
        row_values = extract_values_from_string(row)
        customer_data = dict()

        for column_index, column_name in column_names_list.items():
            column_value = row_values[column_index]
            customer_data[column_name] = column_value

        column_value_mappings.append(customer_data)

    return column_value_mappings


def get_customer_data_from_csv(csv_filepath: str) -> List[Dict[str, str]]:
    csv_file = open(file=csv_filepath, mode='r')
    file_data: list = csv_file.readlines()
    column_names, rows = file_data[0], file_data[1:]

    return map_columns_to_values(column_names, rows)
```

This looks much more readable now, right? The code got three times longer than the old version, but now it's way more 
readable. There are also a few layers of abstraction: The top-level function doesn't show much detail. But every time 
you move an abstraction level deeper, it reveals more information.

## Comments lie

Another problem with comments is that they lie. By saying that, I mean that you can't really trust what comments say 
about the code. They always could be outdated and give wrong information about the code.

In the common case, the code we write changes many times and is never "perfect". As the project you're working on evolves 
and the requirements change, the code has to evolve too. Furthermore, nobody can write clean and perfect code instantly.
Writing code is always an iterative process where you revise and improve the code in each step.

These continuous changes make it really hard to keep all the comments up to date. Imagine there is a comment in every 
second line of your code, or even more! On the one hand, it's really nasty and time-consuming having to change a comment 
every time you change something in the code. On the other hand, it's nearly impossible to keep all comments up to date, 
there will always be an unintentionally outdated one. With modern IDEs, it is very easy to refactor code by allowing the 
program to do so. Nowadays, changing names or cleaning up unused code are standards for every professional IDE. But in 
this way, the IDE only refactors the code and not the comments, how could it? It has inadvertently made the comments 
lying about the code.

## So it's not allowed to write comments any more?

After all these problematic issues about writing comments, we could come to the conclusion that we shouldn't write comments 
at all. But I can tell you this is not the case. And you can definitely write really good code with the usage of useful 
comments. First and foremost, this post wants to draw attention to the various problems when writing comments. We can 
also write better code that speaks for itself without writing comments.

There are still a few cases where it's inevitable to use comments. Most projects should have documentation, which often 
uses comments. Especially when the code or some interfaces to use it are available for externals, good documentation is 
essential. Either way, it would definitely make sense to explain the code's functionality when it solves complex problems. 
Then it's quite helpful for others to understand what the code does, without needing to understand the complex code. By 
writing comments like this, they also are less likely to lie about the code after refactoring. But you still have to adjust 
the comments and the documentation whenever the general behavioral changes.

To sum up, comments can be very helpful in writing understandable code. However, overusing them is never a good choice. 
They pose some relevant difficulties that everyone needs to be aware of.


Comments - What you should keep in mind


## About do one thing

Do one thing at a time - As stated in our earlier posts like [DRY Principle (Computer Science)](https://code-specialist.com/code-principles/dry-principle/), [KISS Principle (Computer Science)](https://code-specialist.com/code-principles/kiss-principle/), or even [Comments – What you should keep in mind](https://code-specialist.com/write-better-code/comments/), **readability** should be crucial to anyone's code.

Something that lastingly improves the readability of your code is a technique called "do one thing". It is often confused with the single responsibility principle (SRP), and the names are indeed confusing, in my opinion.

The main concept behind this is to reduce the code's complexity by diminishing the things statements and functions do, to exactly **one simple thing**.

## Garbage Code

To show you an example of how it works and how significant the improvements can be, look at the following (garbage) code:

```python
class Sieve:
    start = 2

    def __init__(self, n):
        self.n = n

    def run(self):
        l = [True] * self.n
        prims = list()
        for i in range(self.start, self.n):
            if l[i] is True:
                prims.append(i)
                for j in range(i + 1, self.n):
                    if l[j] is True:
                        if j % i == 0:
                            l[j] = False
            else:
                continue
        return prims


s = Sieve(120)
print(s.run())
```

## Sieve of Erastothenes

What does this code do? Rarely anybody can tell that after just reading it. If you read it thoroughly or inspect the output

```
[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113]
```

You might find out that this is actually the [sieve of Eratosthenes](https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes) or at least any algorithm dealing with prime numbers. But if you never heard of the sieve of Eratosthenes, you will most likely search a while until you figure out what this code does and why.

And even if you wrote this and are fully aware of what it does, you might forget all of it in just a few days.

## Why is that code garbage?

Some people might argue that the code works perfectly fine, and some might even argue, "but it is optimized!". Besides someone telling you that most likely never heard of broadcasting in Python, he or she also didn't respect the first rule of optimization:

> The first rule of optimization is: _Don't do it._
>
> Bjarne Stroustrup - C++ Coding Standards

And the reason for that is that you never really know what your compiler or interpreter actually does. Things that look complex to calculate might be faster than some "optimized" branch of code. To effectively optimize code, you need profound insights into the language at hand and the compiler or interpreter.

This is a job for **experts** that are specialized in this kind of work. As a developer, you should always rate **readability over optimization**. However, refactorings regarding optimization also should only be done if the time required for computation largely exceeds the expectations.

> The second rule of optimization (for experts only) is: _Don’t do it yet_.
>
> Bjarne Stroustrup - C++ Coding Standards

## Improved Code

With the concept of the sieve at hand and the idea of a simple job, let's rephrase our code in a more meaningful way.

```python
class SieveOfEratosthenes:
    start = 2
    prime_numbers = list()

    def __init__(self, maximum):
        self.maximum = maximum
        self.boolean_array = [True] * self.maximum

    def run(self):
        self.sieve()
        return self.prime_numbers

    def add_prime_number(self, number):
        self.prime_numbers.append(number)

    def is_prime(self, index):
        return self.boolean_array[index]

    def sieve(self):
        for number in range(self.start, self.maximum):
            if self.is_prime(number):
                self.add_prime_number(number)
                self.remove_multiples_from_sieve(number)
            else:
                continue

    def remove_multiples_from_sieve(self, prime):
        for number in range(prime, self.maximum):
            if number % prime == 0:
                self.boolean_array[number] = False


sieve = SieveOfEratosthenes(maximum=120)
print(sieve.run())
```

Isn't this, in contrast, way easier to read and get? Even if your code is still garbage, using the name of the concept as the class name, you can reduce someone else's research effort from hours to minutes as they can easily find what this should be about. The functions themselves are easy to read as the function name represents exactly the one thing the function does.

Thank you for reading this article! I hope I was able to make the point. I am aware that the improved sieve code isn't perfect. If you come up with an even better to read solution, please e-mail us or post a comment. The smartest solution you can come up with will be permanently displayed here.


Do one thing - Not the single responsibility principle (SRP)


## What does KISS stand for?

KISS stands for **Keep it simple stupid**. It is the first usability principle
of product design but is also used as a coding principle. [Legends
say](https://en.wikipedia.org/wiki/KISS_principle#Origin) that the acronym was
minted by [Kelly
Johnson](https://www.lockheedmartin.com/en-us/news/features/history/johnson.html),
a lead engineer at Lockheed. Johnson handed his team of design engineers a
handful of tools and challenged them to build a jet aircraft that was fixable by
what an average mechanic in the field under combat circumstances would have.

## What does KISS mean?

The key design principle itself, however, is as simple as its name indicates:
Keep it simple. This can be simple. But: there are countless ways to describe
something in a complex way, but there might only be one that is precisely and
short. It's not only about simplifying things. You must be able to take a step
back and view whatever you just did from one's perspective, who is totally
clueless. You might have already engaged this problem by writing code and
reviewing it some months after that. Many lines are unreadable crap because you
weren't able to take a step back and simplify the concepts.  

As we mentioned earlier, KISS isn't a principle that is originated in computer
science. It can be applied to design processes in general, such as product or
software design. We, in this case, will focus on how to apply simplistic design
to code itself.

## Code is not written for machines

The code you write and the code you actually execute largely differ, depending
on the language and compiler or interpreter used. In fact, machines couldn't
care less about your code. All the programs and scripts you write are for
humans. You write it only once but read it possibly a thousand times. Thereby
it's your responsibility to make this as easy, and thereby quick, to read as
possible. Your code design objective thereby should be to offer the best user
experience possible. 

## Simple doesn't always mean short

Another mistake that is often made dealing with the KISS principle is that
people try to make code as short as possible. But the shortest solution is
rather seldom the easiest to read. Consider the following "Non-KISS" example:

```python
f = lambda x: 1 if x <= 1 else x * f(x - 1)
```

Now look at this version:

```python
def faculty(number: int) -> int:
    if number <= 1:
        return 1
    else:
        return number * faculty(number - 1)
```

Sure, the first version is also readable, but it is considerably harder to do
so. Adding a few descriptive names, type hints, and splitting the line into
multiple ones gets clearly easier to read. The main goal in design should always
be to be as easy to understand as possible. One of many common bad practices of
developers is to create fancy and unreadable "oneliners". There is absolutely no
reason to do so. This will most certainly lead to someone, if not themself
struggling to decipher it.

## How to apply the KISS principle?

To apply KISS to design and code, there hundreds of ways but, I want to provide
you with some ideas:

### Simplify and explain concepts

Try to code as simple as possible, unfold your concepts, name things properly
and explain with comments where the code itself can't (Most of the time, it can
and should!).
    
### Use descriptive names
    
As easy as this sounds, trying to find [names that indicate something's true
meaning]() can be very challenging. You may try this by telling someone a name
and let them assume what they think that is. Don't be afraid of long variable or
function names. As stated earlier, the machine doesn't care and won't use your
name anyway.
    
### Deconstruct problems into smaller ones
    
Something that does real magic to the readability of your code is deconstructing
the problem and solving just one simple one with each function. Try refactoring
your code and solve a single problem at a time, but with a maximum of precision
and readability.
    
### Try rubber
    
Did you ever try to explain your code to a dumb duck? No? Try [duck
debugging](https://rubberduckdebugging.com/)! By doing this, you may not only
find bugs, but you may also find gaps in your or someone else's understanding of
the current code.
    
### Learn more about Clean Code
    
Many principles and ideas of clean code build upon the KISS principle. By
applying those concepts, you may find it easier to identify the simplest
solution.
    

## References

- The origin of KISS -
  [https://en.wikipedia.org/wiki/KISS\_principle#Origin](https://en.wikipedia.org/wiki/KISS_principle#Origin)
- Kelly Johnson -
  [https://www.lockheedmartin.com/en-us/news/features/history/johnson.html](https://www.lockheedmartin.com/en-us/news/features/history/johnson.html)
- Meaningful Names -
  [https://code-specialist.com/code-principles/meaningful-names/](https://code-specialist.com/code-principles/meaningful-names/)
- Rubber Duck Debugging -
  [https://rubberduckdebugging.com/](https://rubberduckdebugging.com/)
- More Posts on Code Principles Blog -
  [https://code-specialist.com/code-principles/](https://code-specialist.com/code-principles/)


KISS Principle (Keep it simple stupid)


## The DRY Acronym

DRY stands for “**d**on’t **r**epeat **y**ourself”. The DRY principle is one of
the most important principles in software development, if not even the most
important. Whenever you write or read code and find repetition in it, chances
are high you or whoever planned it, didn't plan well enough.

## What's the problem about code repetition?

Code isn't static. When you write code twice you have to test it twice and if
you have to change it afterwards you also have to change it twice, in fact we
already got the four-fold effort to invest. There is also a large chance, you
miss the second occurrence. Seriously, nobody can remind himself to every line
or routine of code he wrote in a project, at least if it isn't an insanely small
one.

> There is a word for software that isn't changed: Hardware
> 
> Unknown author

In fact, redundant code is not only one of the most common causes for bugs, it's
also the cause for unnecessary complex or at least long code. The DRY principle
helps you to avoid these problems.

## Example of duplicated code

```python
first_player_points = [2, 3, 0, 5]
second_player_points = [4, 1, 1, 2]

def get_score_for_first_player():
  return sum(first_player_points)

def get_score_for_second_player():
  return sum(second_player_points)
```

Whats wrong by changing this to:

```python
player_points = {
  1: [2, 3, 0, 5],
  2: [4, 1, 1, 2]
}

def get_score_for_player(player_number: int):
  points = player_points[player_number]
  return sum(points)
```

I am aware that this is a rather simplified example and that the solution
doesn't apply to every problem, but that's not the point. Fact is, by
generalizing concepts and for example moving redundant code to functions you
save time and spare potential bugs. If applied correctly it may also increase
the readability of your code.

## How to apply the DRY principle?

There is no general concept that allows you to always spare repetition, but
there are steps that may help you to minimize it.

### Plan thoroughly 
    
By planing your program or software carefully you may identify patterns and
generalized concepts in an early stage.
    
### Review frequently 
    
Review your code frequently, or even better let someone else review your
code (That will also ensure your code doesn't exceed a certain level of
illegibility).
    
### Use tools that support you 
    
Depending on how large your project is, it's nearly impossible to find
repetition manually. But there are tools that allow you to find repeated
code anyway. For instance PyCharm¹ offers a duplicates tool window that
allows you to identify code repetition.

## References 
- [Link to PyCharm](https://www.jetbrains.com/de-de/pycharm/)


Posts for the code principles Category