DEV Community: Carsten Behrens

Summary of "A Philosophy of Software Design" by John Ousterhout

Carsten Behrens — Fri, 29 Dec 2023 11:36:05 +0000

"A Philosophy of Software Design" is a book written by John Ousterhout.
It summarizes the author's extensive experience in computer science and
his experience of teaching software design at Standford University. The main focus of this book is problem decomposition: "how to take a complex problem and device it up into pieces that can be solved independently." The book provides techniques on how to deal with the complexity of software.

Chapter 1 Introduction (It's all about complexity)

In the first chapter, Ousterhout lays out what the book is about. As software systems are not
limited by practical limitations such as physics, the only limit to what we can create is our ability
to read and understand the code we are writing.

Any program generally gets more complex with time, as new features are always added.
He states that there are two general approaches when fighting complexity:

"Making code simpler and more obvious"
"Encapsulate complexity (also called modular design)"

Next, he explains that, in contrast with physical systems (like bridges and buildings), software systems tend to be more complex, and it isn't possible to fully visualize the design before writing the code.

Therefore, a waterfall model doesn't work for software, and this is also why an incremental approach like agile
development makes more sense when writing software.

The developers should constantly consider design issues since incremental development also means incremental software design. The author finds that reducing complexity is the most important element of software design, so the developers should be focusing on that.

Then, he lays out the two overall goals of the book:

"Describing the nature of complexity"
"Present techniques for minimizing complexity"

He also emphasizes that since the concepts in the book can be abstract, the book should be used during code reviews. A list of red flags at the end of the book can provide some guidance
during these reviews.

Chapter 2 The Nature of Complexity

In this chapter, the author provides us with his definition of complexity.

He defines complexity as follows: "Complexity is anything related
to the structure of a software system that makes it hard to understand and modify the system."

The author notes that complexity is experienced more often when reading code than writing code.
Hence, it is crucial to focus on creating code that others can easily understand.

According to Ousterhout, complexity shows itself in three different ways:

"Change Amplification" which means that a simple change requires changes in many different places
"Cognitive Load" which refers to how much a developer has to know (or keep in mind)
"Unknown unknowns" refers to a situation where it is not obvious what files must be modified

Ousterhout states that two things cause complexity:

"dependencies"
"obscurity"

A dependency exists when "a given piece of code can not be understood or modified in isolation."
However, he acknowledges that dependencies are an essential part of software and that they can never be
fully eliminated.

Nevertheless, one of the goals of software design should be to reduce the amount of dependencies as
much as possible, or at least make the remaining dependencies as obvious and straightforward as possible.

An Obscurity exists when "important information is not obvious."

This can happen due to various reasons:

A non-obvious dependency between two parts of the code base
Inconsistency
Missing documentation (while keeping in mind that a need for extensive documentation could be a red flag in itself)

Ousterhout notes that complexity builds up slowly over time and is hard to eliminate once it has
accumulated. Therefore, he suggests "zero tolerance" towards complexity.

Chapter 3: Working Code Isn't Enough (Strategic vs. Tactical Programming)

In this chapter, Ousterhout identifies the difference between "Tactical Programming" and "Strategic Programming".

Tactical Programmer:

Gets stuff done fast
Doesn't care about complexity building up
Introduces complexity to the system over time

Strategic Programmer:

Focuses on good design while also having working code
Has an investment mindset
Doesn't increase complexity and tries to reduce it constantly

He suggests spending 10 to 20% of development time on "investments." He argues that this investment will start to pay off within a few months, after which the velocity will increase by 10-20%, meaning that
the investment will pay off quickly.

Ousterhout also acknowledges that this "investment" approach is not suited well for early start-ups but that the "tactical" approach hurts a company in the medium to long run.
Finally, he concludes that a tactical approach will speed up the first product launch since the payoff from good design comes so quickly.

Chapter 4: Modules Should Be Deep

In this chapter, the author presents the basic principles of "modular design" while introducing the concept of "deep modules."

Ousterhout notes that one of the most important techniques for managing complexity is to ensure that developers only focus on a small amount of complexity at a time.

In modular design, a system is decomposed into smaller - relatively independent - modules.
A module can be anything, for example, a class, a sub-system, or a service. Ideally, all of our modules would be completely
independent of each other. Ousterhout acknowledges, however, that there will always be dependencies between modules in the real world.
Still, the goal of modular design should be to minimize dependencies between modules.

He states that each module has two parts:

An interface, which refers to the knowledge that a developer needs to work with the module
an implementation, which refers to the actual implementation of the module

He also defines that anything with an interface and an implementation is a module for this book's purpose.
This would include classes but also methods and functions (and also other services or sub-systems).

What's in an interface?

He explains that an interface has two kinds of information: formal and informal.

The formal parts of an interface (such as method parameters) can be checked for correctness by the programming language.
The informal parts cannot be understood or enforced by the programming language. An example of this could be a function that
deletes a file named in one of its arguments. If a developer needs to know any information besides the formal parts, this information is part of the module's interface.

Deep Modules

Ousterhout argues that the best modules "provide powerful functionality yet have simple interfaces."
These modules are "deep," meaning they hide much of their complexity from other modules through simple interfaces.

Deep modules are a good abstraction because only a small amount of the module's complexity is exposed to other modules.
The depth of a module also describes its usefulness. The module's functionality should be weighed against the complexity
of its interface.

Shallow Modules

The opposite of a deep module is a shallow module. Its interface is relatively complex when compared to the functionality
the module provides.

Classitis

Ousterhout notes that his view of deep modules vs. shallow modules differs from that of many developers today.
Many developers have the view that classes should be small, not deep. Ousterhout claims that this approach often leads to a lot of shallow classes, which increases the overall complexity of the system. Ousterhout invented a new syndrome called "classitis" for extreme forms of this programming style.

"Classitis" helps to create simple classes, but the overall system complexity increases when using this coding style:

Since small classes only provide a little functionality, you'll need a lot of them - each with its own interface.
All these small classes accumulate to create a lot of overall complexity
Having a lot of small classes is more verbose than having fewer larger classes due to the boilerplate required for each class

Example: Java and Unix I/O

He believes that an example of this "classitis" is the Java class library. Java in itself doesn't require lots of small classes, but Ousterhout believes that a culture of "classitis" has affected the Java programming community.

To illustrate this, he shows us an example of how to open a file in order to create a serialized object from it.

FileInputStream fileStream = new FileInputStream(fileName);
BufferedInputStream bufferedStream = new BufferedInputStream(fileStream);
ObjectInputStream objectStream = new ObjectInputStream(bufferedStream);

He explains that the FileInputStream object only provides I/O but is incapable of performing buffered I/O, nor can it read or write a serialized object. To enable buffered I/O, it is required to add buffering by creating a BufferedInputStream object. Finally, the ObjectInputStream adds the ability to read and write serialized objects.
Ousterhout notes that the FileInputStream and the BufferedInputStream objects are never used once the file has been opened.
He finds it annoying (and error-prone) that the developer must always remember to create a BufferedInputStream because otherwise, there will be no buffering, and I/O will be slow.
Ousterhout acknowledges that some users might not need or want buffering, but in his opinion, "interfaces should be designed to make the most common case as simple as possible." Buffering should be the default since most users require it.

Chapter 5: Information Hiding (and Leakage)

In this chapter, the author shares one of the techniques for creating deep modules.

According to Ousterhout, information hiding is the most crucial idea to remember while creating deep modules. Information hiding means that each module should encapsulate some functionality.
The only thing visible from the outside of the module is its interface. This means that the implementation of the functionality is hidden.

Information Hiding

Information hiding is so essential because it reduces complexity in two significant ways. First, it simplifies the interface of a module since the module provides its users with a simpler and more abstract view of the module's functionalities.
Second, it reduces dependencies between the modules. For example, if a change is required, but it only affects the parts of the module that are hidden, then that change only affects this module and no other modules that may depend on it.

Ousterhout suggests carefully considering what information can be hidden when creating a module.
If it is possible to hide a piece of information, then it should also be possible to simplify the module's interface, thus
making it deeper.

Information Leakage

The opposite of information hiding is information leakage. "Information Leakage occurs when a design decision is reflected in multiple modules." When information is leaked, other modules that use the affected module will start to depend on this information, thus creating a dependency between modules.

Ousterhout notes that if a piece of information is part of the interface of a module, then it is leaked. However, there are other ways information can be leaked. As an example, Ousterhout describes a situation where two classes have knowledge of a file format (one class could be reading the file in that format while the other writes to the file)
then this information - the file format - is leaked between the two classes. This type of information leakage is called
Back-door leakage is the worst type of information leakage since it is not obvious.

He argues that information leakage is one of software design's most important red flags. He suggests that one should ask oneself, "How can I reorganize these classes so that this particular piece of knowledge only affects
a single class?"

To do this, it can make sense to combine smaller classes into a bigger one or to pull out all the information and
create a new class that encapsulates just that information.

Information hiding within a class

Information hiding can also be applied to methods in a class, which means that a private method within a class should encapsulate some information and hide it from the rest of the class.

Chapter 6 General-Purpose Modules are Deeper

In this chapter, Ousterhout tackles the question of how generic or specific modules should be.
According to Ousterhout, the general-purpose approach is more consistent with the investment mindset mentioned in Chapter 3. Still, he acknowledges that the special-purpose approach aligns more with the agile way of developing software today.

He thinks that the best solution is the sweet spot between general-purpose and special-purpose. This means that a module should provide the features that are needed today while also offering an interface that is general enough to support
multiple use cases.

To illustrate this, Ousterhout provides an example from his software design class where students were asked to build a simple text editor. Many student projects had a Text class that provided methods for - among other things - modifying the text file.

Some projects created a special-purpose method for each text editing feature:

void backspace(Cursor cursor)
void delete(Cursor cursor)
void deleteSelection(Selection selection)
...

Due to this approach, the class had a large amount of shallow methods, each of which was only usable for one of the required features. This also leaked information between the user interface and the Text class
since the Text class had knowledge of the user interface. This is not good because it creates a dependency between the two modules.

A better solution for this would be to make the Text class more generic:

void insert(Cursor cursor)
void delete(Cursor cursor)

With this interface, the Text class could be reused for other purposes than an editor. This solution is also better because it provides better information hiding. There is no need for the Text class to
be aware of the UI-specific features such as backspace or delete.

Ousterhout finds that general-purpose interfaces tend to have simpler interfaces than special-purpose ones.
They also provide better separation between the classes than special-purpose interfaces that tend to leak information between classes.

Chapter 7 Different Layer, Different Abstraction

In this chapter, Ousterhout describes how abstractions should change on each system layer and how to refactor your code base if this is not the case. Software systems are composed of layers, where higher
layers use the functionality provided by lower layers. Ousterhout argues that in a well-designed system, each layer should provide a different abstraction than the layer above or below it. This means that if you follow a single operation through the layers, the abstraction should change with each method call.

The opposite would be the case when the abstractions are not changing or are very similar. According to Ousterhout, this red flag indicates a problem with the separation of classes.

Pass-through methods

One way this problem manifests itself is in the form of pass-through methods. A pass-through method is a method that does very little besides passing the arguments on to the next method, whose signature is similar to that of the calling method.

Ousterhout notes that a method with the same interface is not always bad, but each method should add some
functionality. Pass-through methods do not provide additional functionality; thus, they are bad.

Decorators

Next, Ousterhout describes the decorator design pattern. According to Ousterhout, a decorator object is an object that extends an existing object while providing a similar interface. An example is the BufferedInputStream class shown in Chapter 4.

The purpose of decorator classes is to extend core classes to fit a more specific use case.
However, according to Ousterhout, they tend to be shallow because they add a large amount of boilerplate code (many pass-through methods) for a relatively small amount of new functionality.

Therefore, decorator classes should be kept to a minimum. Ousterhout suggests to consider alternatives such as:

Adding the new functionality directly to the underlying class
Add the new functionality to an already existing decorator class
Create a whole new class

Interface versus Implementation

Ousterhout argues that the interface of a class should be different from its implementation. This means that the representation used internally should differ from the abstractions in the interface.

To illustrate this, Ousterhout presents another example from his software design class text editor project. The Text class usually stored the text in lines within the file. Some of the teams also designed
the interface of the Text class around lines, with methods like getLine and putLine.

However, this interface leads to problems because sometimes text gets inserted in the middle of a line, which means that the callers of this class have to split and join texts. The Text class was much easier to use when
it provided a character-oriented interface.

Pass-through variables

According to Ousterhout, a Pass-through variable is "a variable which is passed down a long chain of methods."
They add complexity because all intermediate methods must be aware of them even though they might not use the variable themselves. This also means that if you need to change this variable or add a new one, you must modify many methods.

He notes that it can be challenging to remove pass-through variables. One approach to do this is to see if an object is already shared by the topmost and bottommost methods. If this is the case, one can
store the needed information in that object. Another option is storing the information in a global variable, although this typically creates other problems.

Ousterhout finds the most fitting solution in most situations is using a context object, one per instance of the system. The context object will allow multiple system instances to coexist in a single process. Still
Ousterhout warns that contexts are far from an ideal solution and that without discipline, a "context can turn into a huge grab-bag of data that creates nonobvious dependencies throughout the system."

Chapter 8 Pull Complexity Downwards

In this chapter, Ousterhout introduces another way of thinking about deeper classes. He argues that a module developer should always strive to make using the module as easy as possible. This also means that one should handle complexity internally within the module when possible, which means that we are pulling complexity downwards.

Configuration parameters

According to Ousterhout, configuration parameters are an example of moving complexity upwards. Instead of defining the behavior internally, a module can export a few parameters that control its behavior. Users of that module now have to configure these parameters and deal with the complexity that comes with that.

Ousterhout recognizes that these parameters can be useful because they allow the user of a module to configure the module to their particular requirements. However, they can also easily be used as an excuse not to deal with complexity internally and pass it to the user of the module instead.

Taking it too far

Ousterhout warns that pulling complexity upwards should be done with discretion and that it can easily be overdone.
Pulling complexity downwards makes sense if it results in the overall reduction of complexity. For example, if the complexity being pulled down simplifies the class's interface,

Chapter 9 Better Together Or Better Apart

In this chapter, Ousterhout discusses the fundamental question of whether two pieces of functionality should be implemented
together or apart. According to Ousterhout, this question applies to all levels of the system, such as functions, methods, classes, and services.

The goal, as always, is to reduce the overall complexity of the system as a whole. To do this, it is tempting to divide the system into many small components since the smaller the component, the simpler it will likely be.

The problem with this approach is that it leads to a high number of components. The more components, the harder it will be to manage them all. This also means the system will need additional code just to manage the components.
Another disadvantage of this approach is that we now have multiple components instead of having one component.
This can make it harder for developers to change the system because they have to modify and be aware of various components instead of one.

If the components are truly independent and don't have many dependencies between them, then this subdivision is good.
Otherwise, it is bad. According to Ousterhout, this will cause developers to need to know a lot of components, which causes a higher cognitive load. It can also lead to bugs if developers are unaware of these dependencies.

Ousterhout notes that bringing together pieces of code is most beneficial if they are closely related.

He also lists a few tips on how to notice that this is the case:

They share the same information. For example, if both share some knowledge about a file format
They are used together, meaning that users of this piece of code also often use the other
They overlap conceptually, meaning that both of the pieces of code are part of a higher-level category
It is hard to understand one of the pieces of code without looking at the other

Separate general-purpose and special-purpose

Next, Ousterhout explains that when a module contains a functionality that can be used for several other purposes, it should only provide this functionality and no other special-purpose code. This allows the module to be independent and reusable in other modules.

Splitting and joining methods

According to Ousterhout, the same questions also apply to methods. Ousterhout finds that - contrary to popular belief - long methods are not always bad. He believes a method containing five 20-line blocks of code is acceptable as long as the blocks are relatively independent and executed in order. This would mean that the method can be read one block at a time; thus, there would not be a benefit in moving the blocks into separate methods.
He explains that this is especially true when the blocks have complex interactions. Because the developer needs to see all the code at once. If they would be in different methods, the developer that works on the
code would be forced to switch back and forth to understand how they work together.

Next, he applies the idea of deep modules to methods. He finds that a method containing hundreds of lines of code is fine if it has a simple interface because this would mean that the method is 'deep.'

Chapter 10 Define Errors Out Of Existence

In this chapter, Ousterhout discusses exception handling and why exceptions contribute disproportionately to complexity and
how to simplify exception handling.

Why exceptions add complexity

Ousterhout notes that, exception-handling code is more complex to write than regular code because exceptions tend to disrupt the normal flow of the code. When an exception occurs, a developer can either move forward to the next step regardless of the exception or abort the operation and throw an error. As the error gets reported 'upwards,' the developer must eventually find a way to handle the exception. Ousterhout states that exceptions usually don't occur often in running systems, so the error handling code is not executed often. Thus, bugs can sometimes go undetected for a long time.

To prove his point, Ousterhout cites a study that found that more than 90% of catastrophic failures in distributed data-intensive systems were caused by incorrect error handling.

Too many exceptions

Ousterhout states that one of the reasons that problems related to exception handling increase is that developers
define too many unnecessary exceptions. According to Ousterhout, most developers are taught that detecting and reporting errors is essential, but some take this to the extreme.

As an example, Ousterhout describes an error he himself made while designing the Tcl scripting language.
The Tcl scripting language had a command called unset, which is used to remove a variable. The command throws an error if the variable that should be deleted doesn't exist. Ousterhout explains that he thought that when someone tries to remove a variable that doesn't exist, it must be a bug, and therefore it should be reported. However, he did not
foresee that the most common use case of unset would be the clean-up of temporary state after a previous operation. Unfortunately, it is often hard to predict the state of a variable at the time of clean-up, especially
after an operation was aborted. Thus, most developers will try to reset all variables regardless of their current state.

Since unset throws an error when the variable doesn't exist, developers end up enclosing every unset call with a
catch statement to ignore all errors thrown by it.

Ousterhout views this design decision as one of his biggest mistakes when designing Tcl.

Define errors out of existence

Ousterhout suggests that the best way to deal with exception-handling complexity is to define your interfaces so that no exceptions need to be thrown. He calls this "define errors out of existence."

As an example, he circles back to the unset command discussed above. Ousterhout states that he should have used a better definition for the unset command. Instead of deleting the variable, the unset command should be defined as ensuring that the variable no longer exists. With the first definition (deleting), the unset command can't do its job
if the variable doesn't exist. With the second definition (ensuring that the variable doesn't exist), the unset command could just do nothing if it doesn't exist. Meaning that it would not have to throw an error.

Mask exceptions

Next, Ousterhout describes the second technique for reducing the number of places exceptions must be handled: Exception masking. The basic idea of this technique is that the lower module handles the error so that the higher-level modules don't need to do it.

He provides TCP as an example since TCP masks packet loss by simply resending lost packets. So that clients are unaware that a problem has occurred.

Exception aggregation

Next, Ousterhout describes the third technique, "exception aggregation." The idea behind exception aggregation is to handle many exceptions with a single piece of code. Instead of having to write exception handlers for each exception, handle them all with a single handler.

As an example, Ousterhout describes the error handling for a missing parameter in a web server. Typically, a service
method will call a low-level method (e.g., getParameter) to get the needed parameters. This method will throw an error if the requested parameter does not exist.

When the students of his software design class implement this, many of them wrap the getParameter call in an exception handler. This approach resulted in a large number of methods that essentially did the same thing - generating an error response.

Ousterhout suggests a better approach would be to let the errors propagate up to the top-level dispatch method and handle them there. Thus, a single handler could catch all of the ParameterNotFound exceptions and generate the error response.

He highlights that this and the Mask exceptions approach - even though they are both the opposite - both aim to reduce places where exception handlers would be otherwise created.

Just crash?

The final technique that Ousterhout describes is just to let the application crash. These errors are either impossible to handle or not worth trying to handle.

Taking it too far

Ousterhout warns that the "masking" and the "defining out of existence" techniques only make sense if the exception information
is not needed outside the module. He stresses that when something is important, it should be exposed.

Chapter 11 Design it twice

In this chapter, Ousterhout argues that one should consider multiple options before deciding on a major design.
To help find the best design, he suggests that one approach the problem from different angles. Then, after one has
designed the alternatives, one should make a list of pros and cons to find the best one. He also provides a few questions
that one should ask oneself:

"Does one alternative have a simpler interface than another?"
"Is one interface more general-purpose than another?"
"Does one interface enable more efficient implementation than another?"

Chapter 12 Why Write Comments? The Four Excuses

In this chapter, Ousterhout points out the excuses developers use to avoid writing comments and why comments play a crucial
role in software design.

1. Good code is self-documenting

Ousterhout states that some people believe a code does not need comments if it is well-written.
He calls this a "delicious myth". He believes that the informal aspects of an interface can only be described in comments.
According to Ousterhout, there are many other reasons as to why comments make sense. For example, one could explain the rationale behind the code or give a high-level explanation of a method.

Comments also save time. For example, it's faster to understand what a method does by reading its description than
by reading the methods code. Another reason for comments is that they allow us to provide additional information to the
user of a module.

2. I don't have time to write comments

Ousterhout observes that although it is tempting to de-prioritize writing comments, they provide a massive difference in maintainability and that the effort spent on them pays off quickly. It is the same investment mindset that is discussed in previous chapters that also applies here.

3. Comments get out of date and become misleading

Ousterhout suggests that code reviews should fix this issue.

4. All the comments I have seen are worthless

Although Ousterhout agrees that some comments are worthless, he suggests that writing good comments is easy once one knows how to write them.

Benefits of well-written comments

In summary, Ousterhout concludes that the idea comments should "capture information that was in the mind of the designer but couldn't
be represented in the code." He argues that good comments save future developers time because they will be able to understand
the intent behind the code better. Therefore, good documentation reduces Cognitive load and helps to reduce Unknown unknowns.

Chapter 13 Comments Should Describe Things that Aren't Obvious from the Code

In this chapter, Ousterhout discusses what information needs to be described and how to write good comments.

Pick conventions

Ousterhout mentions that it is important to pick conventions that decide what and how you will comment.

The most important comments are the interface and the data structure member (e.g., a class variable or a method)
comments. According to Ousterhout, every class interface, variable, and method should have a comment.
Although occasionally, the declaration of a variable is so obvious that a comment would be redundant, he finds it easier to comment it anyway instead of worrying whether a comment is really needed.

Don't repeat the code

Ousterhout states that many comments are not helpful because they repeat the code. It is not very useful if all the information can be easily deducted from the code next to the comment.

Then, he provides a few examples of bad comments.

// Add a horizontal scroll bar
hScrollBar = new JScrollBar(JScrollBar.Horizontal);
add(hScrollBar, BorderLayout.SOUTH)

// Add a vertical scroll bar
vScrollBar = new JScrollBar(JScrollBar.Vertical);
add(vScrollBar, BorderLayout.EAST);

// Initialize the caret-position values
caretX = 0;
caretY = 0;
caretMemX = null;

These comments don't add any information.

/*
 * obtain a normalized resource name from req.
 */
private static string[] getnormalizedresourcenames(httprequest req) ...

/*
 * downcast parameter to type.
 */
private static object downcastparameter(string parameter, string type) ...

/*
 * the horizontal padding of each line in the text.
 */
private static final int texthorizontalpadding = 4;

In this example, the sentences are just made up of the words and the variable names. This is a good indication that a comment isn't helpful.

A first step to writing better comments is to use different words than the words that are already present in the code:

/*
 * The amount of blank space to leave on the left and right sides of each line
 * of text, in pixels.
 */
private static final int textHorizontalPadding = 4;

In this case, we use a word different from "padding" because some people might not know what it means.

Lower-level comments add precision; higher-level comments enhance intuition

Next, Ousterhout explains that comments should be on a different level of detail than the code.
A comment can either be on a higher-level, a lower-level, or the same level as the code.
A lower-level comment is a comment that is more detailed than the code. A higher-level comment provides high-level
information about the code, such as the rationale behind the code.

Ousterhout notes that comments on the same level will likely repeat the code. Comments on a higher level provide intuition by helping us understand the code's overall intent and rationale.

Interface documentation

According to Ousterhout, the most important role of comments is to describe the abstraction an interface provides.
He recalls his definition of abstraction as a "simplified view of an entity, which preserves essential information but omits details that can safely be ignored." He argues that since code isn't able to describe abstracts at a high level, one must provide comments to document the abstraction.

He distinguishes between interface comments and implementation comments. An interface comment is a comment that provides
information about a class or method for the user who wants to use it. The implementation comments, on the other hand, describe how a class or method works internally to implement the functionality. Ousterhout notes that it is crucial to separate these two comments so that the user of an interface is not confronted with the implementation details.

He provides an example of an interface comment:

/**
 * This class implements a simple server-side interface to the HTTP protocol:
 * by using this class, an application can receive HTTP requests, process them, and
 * and return responses. Each interface of this class corresponds to a particular
 * socket used to receive requests. The current implementation is single-threaded and
 * processes one request at a time.
 */
public class Http {...}

Implementation comments: what and why, not how

Ousterhout explains that, implementation comments are the comments that appear within the methods of a class that help the readers understand how it works and what it is doing. Although the focus should not be on how something is done, the focus is what and why.

Cross-module design decisions

Ousterhout states that real systems often end up with design decisions that affect multiple classes. As an example of this
he names the design decisions of a network protocol that affect both the sender and the receiver, which may be implemented in different places.

This can make it hard to decide where the best place to document these design decisions is.
In a case like this, Ousterhout suggests putting the documentation in a place that will naturally be discovered by
a developer working on these classes. If there is no obvious place like that, he suggests having a file called designNotes
that is divided up with labels for each major design decision.

Then, in the code related to this design decision, he suggests putting a comment referring to the designNotes file.

// See 'topic' in designNotes.

Ousterhout notes that one disadvantage is that the documentation is not close enough to the code, so keeping it up to date with the code could be difficult.

Chapter 14 Choosing Names

In this chapter, Ousterhout discusses naming things, which, according to Ousterhout, is one of the most underrated aspects of software design. When variables - and classes, methods, and so on - have good names, it is easier to understand the code because they act like a form of documentation and thus make the code more obvious.

The opposite is true about bad names since poor name choices increase the complexity of the code and can lead to misunderstandings, which can result in bugs.

Example: bad names cause bugs

As an example of a bug due to bad naming, Ousterhout recalls the most challenging bug he ever fixed.
At the time, he was working on an operating system called Sprite. A bug occurred randomly where some files would lose data.
The bug was quite simple but was very hard to find because the naming of the variable was ambiguous. The file system code used the variable name block for two different things. Sometimes, the name block would refer to a physical block on a disk, and sometimes it would refer to a logical block within a file. At one point in the code, there was a mix-up due to this naming, which caused an unrelated block on the disk
to be overwritten with zeros.

Ousterhout notes that a more precise naming, such as fileBlock and diskBlock could have prevented this bug. Hence, he suggests that one should take extra time to choose great names which are precise, unambiguous, and intuitive.

Names should be precise

Ousterhout finds that a name must be precise and consistent for it to be good. The most common problem with variable names is that most of them are too generic and not precise enough. If a name is too broad, it may be confused with other things, which it is not. Ousterhout notes that if one has trouble coming up with a good name for a variable,
this could indicate that the variable may need a more straightforward definition or purpose. For example, a variable could be used to represent too many things; in that case, it would make sense to separate it into multiple variables.

Chapter 15 Write The Comments First (Use Comments as Part of The Design Process)

In this chapter, Ousterhout discusses how comments can help during the design process and why writing them as one writes the code is essential.

Delayed comments are bad comments

He states that almost every developer he has met puts off writing documentation. This is a problem because once this process is delayed, it often means that the documentation does not get written at all. Ousterhout argues that
even if it does eventually get done, the quality of the documentation will not be the same because the developer will have
forgotten some of the details of the design process.

Write the comments first

Instead, he suggests writing the comments before implementing the code. For a new class, he starts by writing the class interface comment. Next, he will write the interface comments and signatures for the most important public methods. Then, he will iterate a bit until the comments and the basic structure of the class feel right. At that point,
he will write the declarations and comments for the most important instance variables. As the last step, he will implement the methods and add the implementation comments.

With this approach, there will never be a backlog of unwritten comments. According to Ousterhout, this approach has three
benefits:

It produces better comments
Design decisions are still fresh on one's mind, so there is no need to remember things
It's easier to focus on the abstraction and the interface of a method when writing the comment first without having to worry about its implementation

Comments are a design tool

An important benefit of writing comments at the beginning, which Ousterhout mentions, is that it improves the system design.
When writing a comment, one can think about the abstraction before actually implementing it.
Also, comments are essential to good system design because they provide the only way to describe the abstraction fully. The very act of writing a good comment forces one to identify the essence of a variable or a piece of code, which also helps improve the overall system design.

Early comments are fun

Another benefit that Ousterhout mentions is that for him, one of the most enjoyable part of programming is the early design phase, where he can think about the abstraction and structure of the class. Ousterhout argues that writing comments during this phase is more fun.

Chapter 16 Modifying Existing Code

In this chapter, Ousterhout shares his views on modifying existing code. He argues that since software development is iterative and incremental, the final design of a system is more influenced by the design decisions that were made during the systems
evolution than the initial design.

Stay strategic

He warns that one must resist the temptation to make quick fixes. Instead, one should consider if the system's current design is still the best for its job and change it if it's not.

Maintaining comments: keep the comments near the code

Ousterhout notes that it's easy to keep the comments up to date when they are near the code. For example, the methods interface comment should be above the method's body.

He also argues that the farther away the comment is from the code, the more abstract it should be.

A comment that gives a high-level overview should not go into implementation details. By doing this, we reduce the likelihood of the comment being invalidated by code changes.

Comments belong in the code, not the commit log

He argues that since the commit log is less likely to be seen than the source code itself, placing the documentation there does not make sense. Instead, it should be in the source code itself.

Maintaining comments: avoid duplication

Next, Ousterhout suggests avoiding duplicate comments since it is more difficult to update multiple places instead of one. He also mentions that if information is already documented outside the source code, one should reference that external documentation.

Chapter 17 Consistency

In this chapter, Ousterhout shares his thoughts on consistency and how consistency can help reduce a system's overall complexity by making things more obvious. Consistency allows a developer to learn how a thing
is done in one place and apply that knowledge to other places. If a code base is inconsistent, developers must learn each situation separately.

Examples of consistency

Consistency can be applied at all levels of a system. To illustrate this, Ousterhout provides a few examples:

Names
Coding style
Interfaces (meaning interfaces as a language feature)
Design patterns
Invariants

Ensuring consistency

Ousterhout states that consistency is hard to maintain since many people typically work on a project over time. Another reason is that some people (e.g., a new co-worker) might now know about already established conventions.

He provides a few tips that help to maintain consistency:

Document a list that describes the most important overall conventions, such as coding style guidelines.
Enforce the conventions by having a tool that checks for violations and checks the code before it can be committed.

As a final tip on conventions, Ousterhout shares the old saying: "When in Rome, do as the Romans do."

Taking it too far

Ousterhout argues that consistency is only beneficial if it applies to similar things. Meaning that it is fine to do things differently if it makes sense in that case. Ousterhout warns that one should not become overzealous
and try to force things into being done the same way for consistency's sake, as this will only create complexity and confusion.

Chapter 18 Code Should be Obvious

In this chapter, Ousterhout tackles one of the two leading causes of complexity: Obscurity. He then shares some factors that make code more or less obvious.

Things that make code more obvious

First, Ousterhout recalls previously discussed techniques that help to reduce obscurity:
Choosing good names and consistency.

He then offers a few more general-purpose techniques for making code more obvious. The first is to use white space when formatting one's code, as it impacts how easy it is to read. An example of this he provides
two code snippets.

Without whitespace:

/**
  * ...
  * @param numThreads The number of threads that this manager should 
  * spin up in order to manage ongoing connections. The MessageManager
  * spins up at least one thread for every open connection, so this
  * should be at least equal to the number of connections you expect
  * to be open at once. This should be a multiple of that number if
  * you expect to send a lot of messages in a short amount of time.
  * @param handler Used as a callback in order to handle incoming
  * messages on this MessageManagers's open connections. See
  * {@code MessageHandler} and {@code handleMessage} for details.

With whitespace:

/**
  * ...
  * @param numThreads
  *   The number of threads that this manager should spin up in
  *   order to manage ongoing connections. The MessageManager spins
  *   up at least one thread for every open connection, so this
  *   should be at least equal to the number of connections you 
  *   expect to be open at once. This should be a multiple of that 
  *   number if you expect to send a lot of messages in a short
  *   amount of time.
  * @param handler 
  *   Used as a callback in order to handle incoming
  *   messages on this MessageManagers's open connections. See
  *   {@code MessageHandler} and {@code handleMessage} for details.

He also suggests using whitespaces within methods to separate major blocks. He suggests adding a comment above each block to make the code even more obvious.

Things that make code less obvious

In this section, the author shares a few examples of things that can make the code nonobvious.

Event-driven programming

According to Ousterhout, Event-driven programming is a programming style where an application responds to
external occurrences, such as the arrival of a network packet or the press of a mouse button.

One module will be in charge of reporting incoming events (the event module), while other parts of the application register
interest in an event and asking the event module to invoke a given function or method once the event occurs.
Ousterhout finds this programming style hard to follow because the event handler functions are never invoked directly.
Typically, they are invoked indirectly by the event module using a function pointer or interface.

Generic containers

Ousterhout states that many programming languages provide classes to group two or more items into a single object. For example, Pair in Java. He states that one of the most common use cases of these classes is to return multiple values from a method.

return new Pair<Integer, Boolean>(currentTerm, false);

Ousterhout claims that, these generic containers result in nonobvious code because the elements have generic names
that obscure their actual names.

To solve the issue of returning multiple values from a method, Ousterhout suggests just creating a specialized class structure for this use case. That way, one can provide meaningful names for the elements, and it is also possible to add documentation to the declaration.

He notes that, this example illustrates a general rule where "software should be designed for ease of reading, not ease of writing".

Generic containers break this rule because they are easy to write but can be confusing for the reader.

Chapter 19 Software Trends

In this chapter, Ousterhout considers several trends in the software development world and evaluates if and how they might
help to reduce complexity.

Object-oriented programming and inheritance

Ousterhout states that, one of the main elements of OOP is inheritance. He believes that inheritance comes in two forms, which both have a different impact on complexity:

The first form of inheritance is interface inheritance, where a parent class defines the signatures of one or more methods but does not implement them. Ousterhout finds that interface inheritance reduces complexity because one will reuse the same interface for multiple purposes. This is especially true if an interface has many implementations,
because then it is more likely that this interface captures essential features of all the implementations while not being concerned with the implementation details.

The second form of inheritance is the implementation inheritance, where a parent class not only defines the signatures but also implements one or more methods. Subclasses inherit these methods, but they can also overwrite them.
This allows for code sharing among classes because it is possible to provide an implementation of a method to all
subclasses.

A disadvantage to implementation inheritance, according to Ousterhout, is that the inheritance creates dependencies between the parent class and the subclasses. He finds this can lead to information leakage between
the classes in the class tree. For example, he mentions the case where a developer needs to make changes to the parent class; in that case, he may have to check all of its subclasses to ensure they still work as expected.

In an extreme case, the developer would have to check all classes in the tree to ensure nothing breaks.
Therefore, Ousterhout suggests using implementation inheritance cautiously and that one should consider a composition-based approach first.

Agile development

Agile development is a practice that aims to make software development more lightweight, flexible, and incremental.

Ousterhout finds this approach is similar to the one he advocates in this book. However, he also finds that one of the risks of this agile, incremental approach is that it can encourage tactical programming to get a feature done as fast as possible. Another problem, in his opinion, is that some practitioners argue that one shouldn't implement a general-purpose approach right away. They argue that one should first implement a special-purpose solution and then implement the general-purpose one once needed.

Although Ousterhout agrees that this makes sense, he still finds that it encourages a tactical style of programming that can result in a rapid accumulation of complexity.

Unit tests

Unit tests are one of the tenets of agile development, and the practice of writing unit tests has become widely accepted today. Since unit tests help verify that the code works as expected, they also help facilitate refactoring. Hence, he finds that unit tests are crucial in software design as they encourage developers to refactor and improve the code.

Test-driven development

Test-driven development is an approach to software development where developers write the tests before implementing the code. Since the developer's goal is to make the test pass, Ousterhout finds that this approach focuses too much on getting stuff done rather than finding the best design.

The only place where he uses this approach is when fixing bugs. This means that he'll write a test that reproduces the bug and fails, and only then will he start with the implementation of the fix.
Now, if the test passes, one can be sure that the bug is fixed.

Design patterns

According to Ousterhout, a design pattern is a commonly used approach for solving a particular problem.
He finds that one should use the patterns when it makes sense because it would be hard to devise a better solution yourself. However, he warns that one should not try to force it and that a custom approach
is preferred if it is cleaner.

Getters and Setters

Getters and setters are a popular design pattern in software design, especially within the Java programming community. He finds that getters and setters can make sense if one must expose an instance variable. However, he argues that one should be wary of exposing instance variables in the first place since this means that a part of the class's implementation is leaked, violating the idea of information hiding.

He also argues that getters and setters typically are shallow because they are often just one line. They add clutter to the class interface without providing much functionality. Therefore, he believes one should avoid getters and setters as much as possible.

Chapter 20 Design for Performance

In this chapter, Ousterhout discusses how to achieve high performance without sacrificing clean design.

How to think about performance

Ousterhout suggests that, one should neither try to optimize for maximum speed nor completely ignore it. This is because an approach for maximum speed will likely slow down development while ignoring performance
completely will likely lead to many inefficiencies, which will be hard to fix.

Hence, he suggests to use the middle road of these two approaches.

Measure before modifying

Ousterhout observes that, it is tempting to make performance tweaks based on intuition. He argues that one should avoid doing this because intuition can be unreliable. Instead, he suggests measuring the system's existing behavior before trying to fix it.

This will have the benefit of identifying the places where performance tuning will have the most impact while also ensuring that the performance tweak actually improves performance.

He also believes there is no need to retain complex changes if they do not improve performance significantly.

Design around the critical path

When fixing performance issues, the first question one should ask oneself
what is the smallest amount of code that must be executed to achieve the desired outcome.
Also, one should focus on something other than special cases when fixing performance issues. When performance is an issue, one should minimize the number of special cases that must be checked. Ideally, this check should be done at the end, where the special cases can then be handled.

Since performance is less critical for special cases, one should focus on lowering the case's complexity instead of worrying about performance.

Conclusion

Ousterhout concludes that one should focus on simplicity when trying to create fast code, because slow code tends to be slow because it does unnecessary work. He finds that simple code often is fast enough, and
therefore, one does not have to worry about performance much in the first place.

Chapter 21 Conclusion

In this chapter, Ousterhout gives a summary of the topics that were discussed in this book. He also reiterates that this book is all about one thing: complexity.

React Rendering for Dummies

Carsten Behrens — Thu, 24 Aug 2023 17:42:26 +0000

Introduction

React allows us to write Components that automatically update and re-render once the data of the component changes. In this blog post, I will briefly introduce how React archives this.

Hopefully, this blog post will answer the question:
"What happens when I update my component state?"

Counter Example

Let's take a look at an exemplary "component".

Notice that this example does not use any build-step. Instead, we import the required libraries (React, ReactDOM, and Babel) directly inside the browser. I'm doing this because I don't want any framework "magic" to hide what is happening here.

<html lang="en">
<head>
    <title>Home</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js" crossorigin></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js" crossorigin></script>
    <script src="https://unpkg.com/@babel/standalone@7.22.10/babel.js" crossorigin></script>
</head>
<body>
<div id="root"></div>
<script type="text/babel" data-presets="env,react">
    function Counter() {
        const [count, setCount] = React.useState(0)
        return (
            <div>
                <p>Count: {count}</p>
                <button onClick={() => setCount(count + 1)}>+</button>
                <button onClick={() => setCount(count - 1)}>-</button>
            </div>
        )
    }
    const reactElement = React.createElement(Counter)
    const root = ReactDOM.createRoot(document.querySelector('#root'))
    root.render(reactElement)
</script>
</body>
</html>

It is a simple counter that displays the current count and allows the user to increase or decrease it.

There are three parts to this example:

First, the Counter function returns JSX and stores the count value. I will now refer to this function as "Component" as this is the language that people are most familiar with.
Then, we create a ReactElement using the createElement function.
After that, we use ReactDOM to render the ReactElement.

When the user presses the (+)-Button, we can observe that the DOM updates and the new count is displayed.

What happens when you update a state variable

When a user clicks the (+)-Button, we'll call the setCount function to update the count state. Updating the count state will trigger React to call the Counter component.

The process of React calling the Counter component is often referred to as "rendering". Each time we update the state within our component, React will "render" the component.

It is essential to understand that calling the Counter function does not update the DOM. That part gets handled by ReactDOM.

Modifying the DOM

Updating the DOM is slow, that's why ReactDOM will decide which parts of the DOM need to be modified by comparing the old JSX that our Counter component returned with the new JSX.

Before:

<div>
    <p>Count: 0</p>
</div>

After:

<div>
    <p>Count: 1</p>
</div>

The process of finding the minimum number of changes that must be made to the DOM is called Reconciliation.

In our case this is pretty simple, React just has to update the number within the P-Tag. Note that it will not update the whole component, just the elements that need to be changed.

Event bubbling for Dummies

Carsten Behrens — Sat, 19 Aug 2023 22:27:14 +0000

Before we can go into what Event bubbling is, we have to make sure that we understand what an Event is.

An Event is something that happens on a webpage, for example, a user clicking on a button or an error that occurs.

Events are fired and then handled via an event handler. (Or ignored if we don't have any event handler listing for that Event)

Events in action

An example of an event being fired and an event handler looks like this.

<button>Click Me</button>
<script>
    document.querySelector("button").addEventListener("click", (event) => console.log(event))
</script>

So what is happening here is the following:

We search the button via the querySelector
We attach an event listener
We console.log the event

Now let's go into event bubbling.

Event bubbling

The example above is pretty straightforward, but what happens if we don't attach the event handler to the button directly?

<div>
    <button>Click Me</button>
</div>
<script>
    document.querySelector("div").addEventListener("click", (event) => console.log(event))
</script>

In this case, we attach the event handler to the div that is the parent of the button.

Even though the event handler is not attached to the button, the event handler still gets called.

This is because the event "bubbles" up from the child element to the parent element and so on.

It is noteworthy that the event will keep "bubbling up" after an event handler has already handled it.

<div>
    <button>Click Me</button>
</div>
<script>
    document.querySelector("div").addEventListener("click", (event) => console.log(event))
    document.querySelector("button").addEventListener("click", (event) => console.log(event))
</script>

Both event handlers will be called.

Integration Tests using Vue 3 and Pinia

Carsten Behrens — Wed, 19 Apr 2023 17:25:51 +0000

Introduction

In this article, I will show you how to write integration tests for a Vue 3 app that uses Pinia for state management.
I will be using this todo app by ar363 to demonstrate the process.

I do this because I find it easier to explain things when I work with a concrete example.

Installing Dependencies

First of all, we need a test framework to run our tests. We'll use Vitest for this.

npm install --save-dev vitest

Next, we'll add the Vue Test Utils. This library provides a lot of useful functions to test Vue components comfortably.

npm install --save-dev @vue/test-utils

Setup

Vitest uses Vite under the hood and uses the same configuration file. This is great because it means you don't have to duplicate your configuration between the two tools.

As we are working on a Vue 3 app, we'll need to ensure that the @vitejs/plugin-vue plugin is installed and used within our vite.config.ts configuration.

Add a vite.config.ts or a vite.config.js file to the root of your project.

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [vue()]
});

Configuring Vitest

Next, we'll configure Vitest. This is done by creating a vitest.config.ts or a vitest.config.js file.

import { defineConfig, mergeConfig } from "vitest/config";
import viteConfig from "./vite.config";

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      environment: "jsdom", // Use jsdom environment, which is needed for testing components that use the DOM
    },
  })
);

By default, vitest looks for any files that match this pattern ['**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'].

This means that we can place our tests anywhere in our project as long as they match this pattern.

I like to put my tests in a separate folder, so I'll place them within a src/tests folder.

We'll also add the following script to our package.json file.

{
  "scripts": {
    "test": "vitest"
  }
}

Writing the first Test

When writing integration tests for Single Page Applications, I like to use the root component as the starting point.

I do this because the root component will include all other components, so testing this component will make sure that all components work together as expected.

Since this test doesn't have to know about the implementation details of any subcomponents (also known as "black box testing") it will be robust and have a good chance of catching real bugs.

We'll create a tests folder inside our src dir and add a HomeView.test.ts file.

describe("HomeView", () => {
  test("should be able to add and complete todos", async () => {
    const wrapper = mount(HomeView, {
      global: {
        plugins: [createPinia()],
      },
    });
    const todoInput = wrapper.find("[data-testid='todo-input']"); // Find the todo input
    const addTodoButton = wrapper.find("[data-testid='todo-add-button']"); // Find the add todo button

    // Create the two todos
    await todoInput.setValue("First Todo");
    await addTodoButton.trigger("click");
    await todoInput.setValue("Second Todo");
    await addTodoButton.trigger("click");

    const todos = wrapper.findAll("[data-testid='todo-item']"); // Find all open todo items

    // Check if there are two open todos
    expect(todos.length).toBe(2);

    // Check the first todo
    await todos.at(0)?.setValue("checked");
    const doneTodos = wrapper.findAll("[data-testid='todo-item-done']"); // Find all done todo items

    // Check if there is one done todo
    expect(doneTodos.length).toBe(1); // Check if there is one done todo
    expect(wrapper.findAll("[data-testid='todo-item']").length).toBe(1); // Should still have one open todo
  });
});

A few things to note here:

We use the mount function from @vue/test-utils to mount the component.
We use the createPinia function from pinia to create a new pinia instance. We don't mock our store, because we want to test the real store.
We use the data-testid attribute to find elements within our component. This makes our tests more robust. See the rationale behind this here.
We don't try to test the implementation details of our components. We test the component like a real user would.

You can find the full code for this example here.

Vue Form Validation using Yup

Carsten Behrens — Mon, 30 Jan 2023 20:34:38 +0000

This blog post will show you how to validate forms in Vue 3 using Yup.

Setup

In this blog post, I will use the following setup:

Vue 3 with TypeScript, Prettier, and ESLint.
Yup, for form validation.

If you don't use TypeScript, you can skip the parts specific to TypeScript.

Before we can start, we will have to add Yup as a dependency in our project.

npm install yup

Simple Form Validation

Creating a form

First, we will create a simple form with a single input field.

<template>
  <form @submit.prevent="validateForm">
    <label for="name">Name</label>
    <input type="text" id="name" v-model="formInput.name" />
    <button type="submit">Submit</button>
  </form>
</template>

<script setup lang="ts">
import { reactive } from "vue";

const formInput = reactive({
  name: "",
});
</script>

Adding a validation schema

Now that we have a form, we can add a validation schema. To do this, we will use Yup.

Yup allows us to create a schema containing each field's rules. In our case, we only have one field, name.

import { object, string } from 'yup';

const schema = object({
  name: string().required('Name is required'),
});

The field name should be a string and is required.
Please note that when using Yup, if a string is required, then an empty string is not allowed.

Validating the form input

We can validate the form input now that we have our form and schema.

const validateForm = () => {
  try {
    schema.validateSync(formInput);
  } catch (error) {
    console.log(error);
  }
};

We'll show an error message in the console if the validation fails.

Our complete component looks like this:

<template>
  <form @submit.prevent="validateForm">
    <label for="name">Name</label>
    <input type="text" id="name" v-model="formInput.name" />
    <button type="submit">Submit</button>
  </form>
</template>

<script setup lang="ts">
import { object, string } from "yup";
import { reactive } from "vue";

const formInput = reactive({
  name: "",
});

const schema = object({
  name: string().required(),
});

const validateForm = () => {
  try {
    schema.validateSync(formInput);
  } catch (error) {
    console.log(error);
  }
};
</script>

Now that we have a simple form validation, we can address some missing features.

Our form only has one field
We don't show any error messages to the user; without this the user will not know what went wrong.
We only validate the form when the user submits the form, the user experience would be improved if we validated the form as the user types.

I'll address these issues in another blog post if there is enough interest.

Scoped Slots in Vue for Dummies

Carsten Behrens — Mon, 02 May 2022 18:54:52 +0000

What are scoped slots

To easily understand scoped slots, it is helpful to revisit the concept of regular slots.

Slots allow us to provide markup to a child component, this markup then gets rendered inside the child component.

E.g.:

<template>                                                                                          
  <child-component>                                                                                 
    This will get rendered inside the slot inside the child component -                             
    it is called the slot content.                                                                  
  </child-component>                                                                                
</template>                                                                                         

<script>                                                                                            
import ChildComponent from "./components/ChildComponent.vue";                                       

export default {                                                                                    
  name: 'App',                                                                                      
  components: {                                                                                     
    ChildComponent                                                                                  
  }                                                                                                 
}                                                                                                   
</script>

So what are scoped slots?

Scoped slots are exactly like regular slots, with the difference that we pass data from the child component to the parent component. This data can then be used inside the slot content.

How to use scoped slots in Vue 2

The child component:

<template>                                                                                          
  <div>                                                                                             
    <slot v-bind:example="example">                                                                 
    </slot>                                                                                         
  </div>                                                                                            
</template>                                                                                         

<script>                                                                                            

export default {                                                                                    
  name: 'ChildComponent',                                                                           
  data() {                                                                                          
    return {                                                                                        
      example: 'just some data...'                                                                  
    }                                                                                               
  }                                                                                                 
}                                                                                                   
</script>

How the data gets used inside the parent:

<template>                                                                                          
  <child-component>                                                                                 
    <template v-slot:default="slotProps">                                                           
      Now we can use the data from the child component here: {{ slotProps.example }}                
    </template>                                                                                     
  </child-component>                                                                                
</template>                                                                                         

<script>                                                                                            
import ChildComponent from "./components/ChildComponent.vue";                                       

export default {                                                                                    
  name: 'App',                                                                                      
  components: {                                                                                     
    ChildComponent                                                                                  
  }                                                                                                 
}                                                                                                   
</script>

You can find the full code for this example here.

How to use scoped slots in Vue 3

The child component:

<template>                                                                                          
  <slot :example="example"></slot>                                                                  
</template>                                                                                         

<script setup>                                                                                      
import { ref } from 'vue'                                                                           

const example = ref('just some data')                                                               
</script>

How the data gets used inside the parent:

<template>                                                                                          
  <child-component v-slot="slotProps">                                                              
    Now we can use the data from the child component here: {{ slotProps.example }}                  
  </child-component>                                                                                
</template>                                                                                         

<script setup>                                                                                      
import ChildComponent from './components/ChildComponent.vue'                                        
</script>

You can find the full code for this example here.

Why use scoped slots

So why would we want to use scoped slots in vue?

We use scoped slots to give more responsibility to the consumer of our component this allows our components to be more reusable!

Example: Scroll Progress Bar

To see a real-life example of how this amazing Vue feature can be used, take a look at this library here.

Using scoped slots, we give the user full control over how the component should look. The only downside to this is that we also expose more complexity to the user of our library/component.

SOLID: Dependency Inversion Principle in JavaScript and TypeScript

Carsten Behrens — Tue, 18 Jan 2022 18:41:19 +0000

In this series of blog posts, I will take a look at SOLID Principles in the context of JavaScript.

SOLID is an acronym referring to the SOLID Principles of class design that were popularized by Robert C. Martin.

THE DEPENDENCY INVERSION PRINCIPLE

Modules that encapsulate high-level policy should not
depend upon modules that implement details. Rather,
both kinds of modules should depend upon abstractions.
Robert C. Martin

Or in a more simple way:

A. High-level modules should not depend on low-level modules. Both should depend on abstractions.

B. Abstractions should not depend upon details. Details should depend upon abstractions.

This means that an abstraction (interface or abstract class) should not depend on a detail (concrete classes).

The goal of the DIP is to decouple high-level modules from low-level modules. This safeguards the higher-level modules from possibly breaking changes in lower-level modules.

The best way to explain the DIP is to look at the flow of control of an exemplary program. Let's say we have an API that allows us to create video courses. We have a CourseController that handles the routing, validation, and stuff like that.

Then we have a CourseService that will handle the creation of courses, get courses, and so on...

The simplified code for a class of such program might look like this:

class CourseService {
  // ...
}

class CourseController {
  constructor(courseService: CourseService) {
    this.courseService = courseService;
  }

  async get() {
      // ...
        const data = await courseService.getCourses()
      // ...
  }
}

In this example we use a constructor function to provide a CourseService to our CourseController class. The CourseService then gets used in the get method of the CourseController.

The flow of control looks like this:

This means that a high-level module depends on a low-level module. The question you have to ask yourself is: Do I want my high-level policy to be polluted by low-level detail?

Now imagine that CourseService itself depends on other modules which themselves depend on even lower-level modules. A change in one of the low-level modules could break modules that depend on it.

To stop this from happening we need to invert the dependency. Basically, we will add an interface between the two classes.

Afterward, the flow of control should look like this:

And the code:

interface ICourseService {
  getCourses(): Promise<ICourse>
}

class CourseService implements ICourseService{
  getCourses() {
    //...
  }
}

class CourseController {
  constructor(courseService: ICourseService) {
    this.courseService = courseService;
  }

  async get() {
    // ...
    const data = await courseService.getCourses()
    // ...
  }
}

We changed the CourseController class in such a way that it only refers to an abstraction of the CourseService (the interface ICourseService), not to a concrete class.

Why and when you should use Vuex

Carsten Behrens — Wed, 13 Oct 2021 08:32:27 +0000

As developers, we sometimes fall into the trap of using technologies just because they are popular and or commonly used together. That's why it can be beneficial to take a step back and truly understand the why of each technology we use.

In this blog post, I will try to do this in regards to Vuex while answering
the following question:

What problem does Vuex solve?
How does it solve the problem?

The Beginning

Let's start with just plain old Vue. You only have one component which includes the state, the template to render your HTML, and methods that modify that state.

Your component has perfect encapsulation and life is good.

Now you add a second component and you pass it some of the state of the first component via props.

Simple enough.

Now imagine the following scenario: The component at the bottom of this graph needs some state from the first component.

In this graph you can see that we pass the needed state through many layers of components, this approach is referred to as prop drilling. It might not seem like a problem by looking at this simple graph, but imagine what this graph would look like in a large application.

Things will start to get messy quick.

But what exactly is the cause of increased complexity when using this approach?

Even if the components in-between don't need the state from the first component, they still need to pass them to the next component. (Increased Coupling)
The number of changes needed to rename a prop is high. (Code Duplication)
It becomes less simple to locate the place in your code where the state is modified. This increases cognitive load. (Increased Complexity)

Your Application Grows

As your application grows, it will eventually come to a point where more and more state is needed by multiple components scattered across your component hierarchy.

You also often find the need to control part of the state of the parent component by one of its children,which means you'll now have to trigger events from the child component and listen for them in the parent.

This of course increases coupling even more.

In the graph below you will see a small application that has gotten to the point where global state can simplify the code.

Just imagine what a nightmare it would be if the component red component (bottom left) needs to access state from the yellow component (bottom right).

To solve this issue we have three different options:

Move the state up to the top of our component hierarchy, so that we can then pass it down again to the components that need it.
Send the state up the component hierarchy via events and then pass it down via props.
Use global state.

By now you should know that the first two options can become very complex, especially in larger applications. So let's take a look at the third option.

Global State

This is where global state comes in, it allows us to access and modify the state from anywhere within our application.

In Vue this could be as simple as doing this:

methods: {
    toggleTheme: () => {
      this.$root.darkMode = true;
    }
}

Now you could use it in other components simply by referencing this.$root.darkMode.

As you can probably tell from the example code we are setting the theme for the application.

In this case, this should truly be available throughout the program, it would not make sense for this to be bound to a component.

The question then arises: If this is approach is so simple why do we need Vuex to manage our global state instead?

The problem with global state is that it has some inherent problems:

The global state can be modified from anywhere, this means it becomes harder to predict what the value is at runtime and where it was changed from. (Increased Complexity)
If two components depend on the same global variable, this means that the components are now coupled. This is not only a problem of global state as we had the same problem before. But it is a new problem if you didn't have any coupling between the components before.
Makes testing harder. Since now you'll have to mock the global state. (Increased Complexity)

Flux

This is where Flux comes in. Flux is a pattern for managing data flow in your application.

I'll try to give you a quick introduction to Flux below.

So what is Flux?

Going back to our example from the graph above, where the bottom left component (red) needs state from the bottom right component (yellow).

Here is how this would work in Vuex (which is the official Flux implementation for Vue):

Components dispatch actions (e.g. user clicks a button)
The store updates based on what the action it receives (e.g. "increment" will increase the count property in the store)
Components update when the store updates

Instead of coupling the data with the component, Flux (and therefore Vuex) keeps the data completely separate.

Different implementations of Flux often use different terms and add or omit a few parts of the original pattern, so it can get confusing sometimes. But at the root, all of the implementations follow the same principle. If you want more information about Flux,you can get a great overview here.

Vuex

Ok, so Vuex is the official Flux implementation for Vue, and just like the example above shows,
it solves the same "prop drilling" problems like our global state example from the "Global State" section above.

One of the main differences between the global state example and Vuex is that Vuex actually encourages its users to keep most of the application state inside the store. That way Vuex becomes the single source of truth.

At the same time, it tries to mitigate the problems that global state inherently has by providing a better developer experience.

So what are the advantages of Vuex compared to using regular global state?

Standardized patterns for modifying state
Better integration with Vue
Great Debugging Tools and integration in testing utils to allow for easier testing
Better support since it's used a lot by the Vue community

Overall Vuex offers great value for medium to large applications. When you have a small application you
might consider not using it.

The basics of JWT (JSON Web Tokens) for Dummies

Carsten Behrens — Tue, 03 Aug 2021 19:45:38 +0000

JSON Web Tokens are a proposed internet standard that allows for stateless authentication.

Use

JWT are mostly used to authenticate users in the context of websites / web application.

Example

Before going into the nitty-gritty here is a simple example of its usage:

Let's say we have a Web Application called Tweeter, this Web Application can do a bunch of fancy stuff but let's focus on the user profile. Now obviously each user should only be able to access their own user profile settings.

So very simply User with ID 123 should only be able to access profile settings of User ID 123.

Here is how the authentication flow could look like:

Looking at this diagram you'll notice two things:

1.

Once the User/Browser has the Token, the DB is no longer needed to authenticate the user.
This is why it's called stateless authentication.

2.

With the Token, we can send information about the user, in this example the ID.

This information can then be verified using the Secret Key.

The JWT

The Token itself is either send via Cookie or via Authorization Header.

E.g.:

Authorization:
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2Mjc5MjgyMzksInVzZXJSb2xlcyI6WyJBRE1JTiIsIkRCX1JFQUQiLCJEQl9XUklURSJdLCJ1c2VySWQiOjEyMzQ1LCJpYXQiOjE2Mjc5MjgxMTl9.8vTwsBOp8LSa0sdc0nWAUnmWAAgOnS0ElB3bfaiSRfQ

The mangled mess of letters and numbers is nothing more than encoded JSON. Notice that it is encoded not encrypted that means we can easily decode it.

JSON.parse(atob("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9")) // This will return: {alg: "HS256", typ: "JWT"}

Using the jwt.io website we can make it really easy for ourselves. Just paste the JWT and get the decoded JSON data.

The JWT is made up of three parts:

Header:

Contains information on the signing algorithm that was used.

Payload:

Contains the claims. Like UserId and any other information you want to use, but also a bunch of reserved Claims that you can see here.

Footer:

Contains the signature of the token that can be verified with the Secret Key. If the Token gets changed in any way, it won't be valid anymore.

If you need more input on this topic I highly suggest you watch this presentation, it's great.

What is Business Logic anyway?

Carsten Behrens — Wed, 28 Apr 2021 09:31:08 +0000

The term business logic is often used by developers when talking about software design and clean code. But understanding what it means can be confusing.

Here is the definition of business logic on Wikipedia:

In computer software, business logic or domain logic is the part of the program that encodes the real-world business rules that determine how data can be created, stored, and changed. It is contrasted with the remainder of the software that might be concerned with lower-level details of managing a database or displaying the user interface, system infrastructure, or generally connecting various parts of the program.

After reading this definition I had more questions.

Do business rules only apply to business matters?
What if my application does not have a database?
Does every application have business logic?

I'll try to answer all of these and some other questions here.

CLEARLY UNCLEAR

The truth is, that the term is not clearly defined, there are too many opinions of
what the definition of business logic is, and it's often way easier to understand the term in context.

Now it seems like I am not the only one that is confused by this term, as even the definition on WikiWikiWeb is a hot mess.

The best way to explain business logic is by using an example.

Imagine that we want to build a web app that calculates the BMI (Body Mass Index).

After users calculate their BMI the information gets saved in a database.

In this example, the business logic could be boiled down to a simple function:

function calculateBmi(weight, height) {
  return weight / Math.pow(height, 2);
}

// This is a simplified version. 
// You'll also need to consider different units, metric vs. imperial and so on...

Obviously business logic often gets way more complex in real-life applications. Try to keep this in mind.

Now let me show you the difference between business logic and the rest of the application.

Let's say we choose Vue as a modern frontend framework to help us build this web app.

Think about all the other code that our imaginary web app will likely have:

A form users can enter the information
Some kind of form validation
A database connection so we can store the data
Templates to generate our HTML
CSS to make our web app look pretty

All of this code is NOT part of our business logic.

Since that code either deals with the presentation or the database, it is
not part of our business logic.

What if we changed our frontend framework?

The calculateBmi function would remain unchanged.

What if we changed our database?

The calculateBmi function would remain unchanged.

These questions can help you identify business logic easier. If the code could
remain unchanged, it's a tell-tale sign that it is business logic code.

If you struggle with this example here is another example from the
WikiWikiWeb I have mentioned above:

It may help to consider a simple but illustrative example like computer chess:
The game itself, i.e., the board and the pieces, their movements, and how the
rules of the game are handled independent of any display or user interaction
is business logic.

FAQ

Do business rules only apply to business matters?

No, that's why the term business logic is also often called domain logic.

What if my application does not have a database?

Your application can still have business logic. Since the business logic can be independent of your database anyway, it does not matter.

Does every application have business logic?

Not all applications have business logic. On my Github I have a simple exemplary Vue application. It uses the Catfacts API and the
Unsplash API to get a random cat breed and load a picture of that breed.

So all it does is fetching data and displaying it. It does not have business logic.

Photo by Hunters Race on Unsplash

How to Make your If Statements more readable by using this ES2020 Feature

Carsten Behrens — Mon, 26 Apr 2021 10:40:14 +0000

Have you ever written an if-statement like this?

// The object we are working with
const car = {
  make: {
    name: "bmw",
    founded: 1916,
    country: "germany"
  }
}

if (car && car.make && car.make.name && car.make.name === "bmw") {
  // Do something.
}

In JavaScript, we often check if each property exists.
We do this because we don't want to run into errors.

The only problem:

It's ugly
It's harder to read than it needs to be
Noise-to-Signal Ratio is high

THE BETTER WAY

Thanks to optional chaining which is part of ES2020, you can now do this:

// The object we are working with
const car = {
  make: {
    name: "bmw",
    founded: 1916,
    country: "germany"
  }
}

if (car?.make?.name === "bmw") {
  // Do something.
}

Beautiful
Easier to read
Noise-to-Signal Ratio is low

In my opinion, it's the best way to check if a property exists in your if statements.

How I became a professional self-taught developer in Germany while working a full time job

Carsten Behrens — Mon, 15 Mar 2021 20:29:31 +0000

There are many stories online from self-taught developers that share their journey.
Most of these stories are from developers in the USA.

I have never stumbled upon a story from a German self-taught developer or from someone that got a job in Germany as a self-taught developer.

Since that's exactly what I did, I decided to share my journey here.
Hopefully, this blog post will help someone to avoid the mistakes that I made and also learn from the good decisions that I made.

Basically, I want to write the blog post that I would have needed back when I started programming.

At the end of the blog post, I will give you a short TLDR of all the mistakes to avoid and tips to follow.

First I have to mention one disclaimer:

Technically I am not fully self-taught since I did finish an apprenticeship as an "IT Specialist" (Fachinformatiker für Systemintegration). I still consider myself self-taught because I did not learn any real programming during that time.

The beginning

My story is not special, I guess many of you reading are in the same situation that I was in back in the day:

I was unhappy with my career and I wanted to change that.

I was living in a smaller city at the time and as far as I knew there were not a lot of opportunities for developers there.

So I decided to quit my job and get a new job closer to the nearest bigger city in hopes of getting a developer job there once I taught myself programming.

Looking back this was a great decision, not only was I closer to the action, but it also took away some distractions. Since I was new to the city I had no friends there, and I made sure not to make any.

My plan was simple:

Get a new job in near a big city
Teach myself programming in one year
Get a job as a professional programmer

First mistake: Getting a stressful job

So here I am, new job, new city. Everything is cool, right? Well actually no.

I didn't do my research when searching for a job. I just took the first job that wanted to hire me because I didn't want to stay there long anyway.

Big mistake.

The job was extremely stressful and also mentally taxing - the last thing you need when you want to learn to program on the side. Often I would get home completely sapped so much so that I needed a nap just so I could focus on anything again.

The schedule

Since I had my goal to become a full-time developer in one year, I needed to break this big goal down into actionable steps. So I decided that I would do three hours of programming every day besides my 8 hours at my full-time job.

When you are trying to become a full-time developer while also working a full-time job, you'll quickly realize that you don't have much time left after your job, commute, cooking, house chores, and all that kinda fun stuff are done. That's why I really started to pay attention to every minute I was spending during the day.

I also wrote down how many hours I managed to program each day so that I would not cheat myself.

During this time my ideal schedule looked like this:

Monday - Friday

06:50 - Wake up and Shower
07:15 - Commute to work
08:00 - Start work (actually I was always 5 minutes late, but let's not talk about that)
17:00 - Finish work
17:50 - Get Home and eat something
19:00 - Take a nap
20:00 - Start programming
23:00 - Wind down at the end of the day and go to sleep

On Saturday and Sunday, I would not have a set schedule, but I would do at least 3 hours of programming.

That schedule was rough. I would not recommend that schedule to anyone, and it will lead to burnout in the long run. Also, turns out sitting in front of a computer 12 hours a day not doing any sports is unhealthy, who knew?

Second mistake: No direction

When I started I tried to learn python, because I've read that it's a great language.

I got bored (because I had no project in mind) and switched to C++, then I was going back and forth between C++ and Python.

Also, I was reading all kinds of programming books that were way too advanced for me at that time.

That's when it dawned on me that I had just wasted a huge amount of time reading books, when in reality all I needed to do was to get my hands dirty and do some actual programming.

You don't learn programming by reading books, you learn programming by programming.

Now don't get me wrong, I am not saying that you shouldn't read books about programming.

In fact, I think it's really important to start reading programming books once you mastered the basics, it's the fastest way to learn about software architecture, clean code, and design patterns. But I believe in the first few months you should spend most of your time programming.

I was devastated - my approach was not working. Like a truck
that was stuck in the mud, spinning its wheels, I was going nowhere.

I knew I needed to start from square one.

Getting on the right path

I realized that I needed to create some kind of project, that I could show
to potential employers.

That's when I did some research and decided that web development was my best bet.

There are lots of jobs in web development, you can easily share your project, and there is no shortage of great learning resources.

So I started learning HTML, CSS, JavaScript, and React.

After learning the basics, my goal was to create a simple time tracking web app and use that project to get me a programming job.

I bought some Udemy courses and choose one where the end product was similar to the app that I wanted to create. I still think Udemy courses are a great learning tool if you want to learn a new stack. In the beginning you often don't know what you don't know.

That's why having someone more experienced being your mentor can be so powerful.

In total this project took me around 2 months to complete.

You can see the repo here. Now obviously I had no idea what I was doing - the code looks horrible - but I managed to get a working application that I could share with potential employers.

The application process

Nobody likes rejection. Maybe that's why I waited 8 months after I started programming to send out applications.

Looking back, I probably could've sent out applications earlier. I've seen people with similar stories like mine get jobs with pretty weak portfolios. So you might want to consider sending out an application after 3 months or so.

I tried to put myself in the shoes of HR. Let's say you get 50 applications for one job. 49 of those applications have some kind of experience or some kind of degree.

Then there is my application:

Zero experience
No degree that's useful for programming
My CV did not show any proof that I could program

What do you think HR will do? They would probably - and rightly so - send me a nice rejection email and move on to the next candidate to fill the position.

That why I made sure to emphasize my personal projects, I knew that an ordinary application would not be the right thing to do in my situation.

My situation was different, so I figured that my application should also be different.

I knew that I had to get past HR and get some developer to look at my project, that was my only chance. So the gist of my application was this:

I have no experience, but please look at my personal projects.

This worked surprisingly well.

I probably send out around 15 applications and 4 interviews before I got my job. In the end, it took me eleven months to reach my goal of becoming a professional programmer.

TLDR

Start programming ASAP, you learn programming by programming
Give yourself a deadline of when you want to be a professional programmer
Focus on one programming language
Choose a programming language that is widely used
Create a project on GitHub that you can show to potential employers
Try to do one step every day, learning to program is a marathon, not a sprint
Get a mentor or buy an Udemy course in the technology you are interested in