Forem: Jakob Durstberger

Sharp Knives and Dull People

Jakob Durstberger — Tue, 21 Nov 2023 09:28:18 +0000

"We have to make sure that no one can do it wrong."

This sentence, or variations of it, is something I have heard a lot since I have become a programmer. And it is something I wholeheartedly believed in myself for a long time.

"Doing it wrong", in this case, refers to implementation patterns in a codebase or software system.
At the core lies a belief that if we just "lock something down enough" or "make it foolproof", programmers will be forced to follow the "correct" pattern.
I think of this as the cookie-cutter approach: You give developers a few cookie-cutters, and you always end up with the right solution, right? "Developers won't have to think about doing the right thing" is another one of those phrases often tossed around in those conversations.

Since when do we not want developers to think?!

Please don't misunderstand me. I see great value in having uniform approaches within a code-base or software system.
Uniformity does reduce mental load and increases trust in the system. But in my experience, trying to take it too far will backfire for a few reasons.

Firstly, people will find a way to navigate around the desired pattern. Unfortunately, general-purpose languages are so, well, general-purpose that it is nearly impossible to ultimately dictate a pattern without any possibility of modifying or circumventing it. This is something I have experienced myself many times when onboarding a new team member. They only needed a few days to "break" a pattern, intentionally or unintentionally. So you will still have to explain the pattern, its dos and don'ts, and why it exists in the first place.

Secondly, you will run into situations where there are very legitimate reasons to break a pattern. If your design or language of choice does not allow for that, then you will find yourself either stuck or needing to make ugly workarounds.
It ends up being an endless battle of finding ways to enforce the patterns while trying to keep the enforcement flexible enough to allow for untypical situations to be handled gracefully.

Thirdly, forcing people to apply patterns and making them believe that, if they do, nothing can go wrong will often lead to them switching off their minds. And while I, as already stated, do believe in uniform approaches to reduce mental load, I don't want anyone to switch off their mind while they are programming.

"I like giving people sharp knives and teaching them how to use 'em" - Toby Clemson, fellow programmer

Toby once said the above to me when we were working on a project together, and it has stayed with me since then.
I like thinking of my team members as people I can trust, people I can give sharp knives which they want to wield with care and attention. And if they don't know how to do something, they will want to learn and ask for help. The idea of making sure that they can't do anything wrong now leaves a bad taste of not trusting team members.

And if you don't trust your team members, you have way more significant problems than the correct application of code patterns.

I don't want to work with dulled-out people using cookie cutters. I want to work with sharp people using sharp knives.

Partial Application and Parameter Ordering

Jakob Durstberger — Mon, 14 Nov 2022 19:21:35 +0000

Introduction

Something that often is given little consideration is the order of function parameters. Admittedly, frequently it doesn't make that a whole lot of a difference, but sometimes, specific parameter ordering can make our life easier.

⚠️This blog uses Clojure for its examples. I think Clojure's terseness is helpful in making good examples. If you don't know Clojure at all, check out my Very Short Introduction to Clojure.⚠️

Let's consider a function that adds value add tax (VAT) to a priced item. In a lot of countries, VAT differs between different types of products. We can easily encode this information in a map.

(def vat-percentages
  {:food-item 10
   :culture   13
   :default   20})

Our function add-vat needs two arguments, vat-percentages and a product that needs to be priced. Therefore there are two ways to order the function parameters.

(defn add-vat
  [product vat-percentages]
  ...)

(defn add-vat
  [vat-percentages product]
  ...)

At first, both options seem viable, but things get a bit more interesting when we use map to price a collection of products.

A primitive implementation that uses an anonymous function, would make the two options still seem pretty equal.

(map (fn [product] (add-vat product vat-percentages))
     products)

(map (fn [product] (add-vat vat-percentages product))
     products)

But this approach doesn't leverage the whole toolkit of functional programming.

Partial Application

An underused tool is partial application.
Partial application allows us to take a function with arguments and pre-fill some of those arguments so we end up with a function that requires less arguments.

This can be demonstrated nicely with the + function.

;normal usage
(+ 2 3) ;=> 5

;partial application
(def add-3 (partial + 3))

(add-3 2) ;=>5
(add-3 9) ;=>12

partial returns a new function which has 3 'baked in' as one of the arguments. We then assign the returned function to a new symbol add-3 as to be able to easily refer to it.

Looking back at the previous implementation of our map invocation we see now that we could try to leverage partial to pre-fill the tax information on our add-vat function.

The only consideration with partial is that arguments are "pre-filled" left-to-right.
This means that if we want to use partial on our add-vat function we have to put the vat-precentages before product.

Let's try it on our VAT example.

(def vat-percentages
  {:food-item 10
   :culture   13
   :default   20})

(defn add-vat
  [vat-percentages product]
  ...)

(defn apply-vat 
  [vat-percentages products]
    (map (partial add-vat vat-percentages) products))

Compare this to the previous example.

(defn apply-vat 
  [vat-percentages products]
    (map (fn [product] (add-vat vat-percentages product)  products))

It might not make a huge difference but it declutters our code and leaves only what's important.
This is just a short example but it shows that parameter ordering makes a difference and enables us to use more tools from our toolkit.

Creating a Heuristic

From experience I have found that ordering parameters from more to less stable works quite well.
What I mean with stable is how likely it is that the value of the argument changes between invocations.

In the above example vat-precentages changes less often than the product that we are pricing.

Another example might help clarifying this way or thinking.
Let's consider a function that makes a network call.
The function requires a logger, a base-url of the api, a token, and then a payload to post.

Using the above technique most likely leads us towards something like this.

(defn post-to-api
  [logger base-url token payload]
  ...)

When the system starts we could use partial to pre-fill logger and base-url. Once a user has authenticated we could use partial again to pre-fill token.

We are then left with a function that only requires a payload and puts little burden on the callee.

Conclusion

Partial application is a powerful tool to make your code more terse and can also be used to abstract required arguments from code further down.
To fully leverage partial application we should order function parameters from most to least stable.

Maybe you give it a go and let me know what you think?

A Very Short Introduction to Clojure

Jakob Durstberger — Mon, 14 Nov 2022 16:48:38 +0000

This guide is not meant to make any arguments about why to learn Clojure but is only meant to give a very quick introduction to syntax basics. I think Clojure is a very elegant language, but the "weird" syntax often puts people off. I will attempt to show so you some basics so you can get an idea of what Clojure looks and feels like.

⚠️ Warning: This guide leaves out a bunch of details and makes some oversimplifications for the sake of brevity. It also assumes that you are comfortable with basic programming concepts.⚠️

Trying It Out

If you want to code along and run any of the following code on your computer then the easiest way to do that is with the REPL.

Just install Clojure (see the official guide) and type clojure in your terminal.

This will start an interactive environment in which you can run Clojure code.

You can verify everything is working by running (println "Hello, World!")

Invoking Functions

If you ran the above snippet, you already invoked your first function, but it is worth looking at the anatomy of a Clojure function invocation.

(function-name arg-1 arg-2 ... arg-n)

The parentheses instruct Clojure to invoke a function where the value in the first position is the function name, and the remaining values are arguments to that function.

(+ 1 2) ;=> 3

In the above example, + is the function and 1 and 2 are the arguments, resulting in the value 3.
If you try this in the REPL then the result will be printed to the terminal.

Defining Variables

You can use def if you need to store a value in an easier-to-remember name.

To keep things simple, you can think of these being defined globally.

(def x 10)
(def y 15)
(+ x y) ;=> 25

Defining Functions

To define functions, you use defn. The generic structure of a function definition looks like this.

(defn function-name
  [arg-1 arg-2 ... arg-n]
  body-expression-1
  body-expression-2
  ...
  body-expression-n)

For example, following function takes a name and prints a personalised greeting.

(defn greet
  [name]
  (println "Hello there, " name))

;Call the function you just created
(greet "Alice") 
;"Hello there, Alice
;=> nil

Two lines are printed because the greeting is printed to the console with println and so is the return value of the function.
Every function returns a value and in this case, the function returns nil (Clojure's version of a null value).

The value of the last expression within a defn is the return value. For example, you could return the name of the greeted person.

(defn greet
  [name]
  (println "Hello there, " name)
  name)

(greet "Alice") 
;Hello there, Alice
;=> "Alice"

Define Scoped Variables

To define locally scoped variables, you can use let.

;a will only be available within the parenthesis of the let
(let [a 1]
  (println a)) ;=> 1

;a is not available anymore
(println a) ;=> Unable to resolve symbol: a in this context

You can define multiple variables within a single let too.

(let [a 1
      b 2]
   ...)

You can, for example, extract the greeting from our above example into a variable to print and return it.

(defn greet
  [name]
  (let [greeting (str "Hello there, " name)]
    (println greeting)
    greeting))

Sequencial Collections

The most straightforward list collection to use are vectors.
You can create one like this.

(def names ["Alice" "Andrew"])

Values within a vector are separated by spaces and you can mix types, but you probably should not.

You can print greetings for a list of names.

(defn greet
  [name]
  (println "Hello there," name))

(def names ["Alice" "Andrew" "R2-D2"])

(for [name names]
  (greet name))
;Hello there, Alice
;Hello there, Andrew
;Hello there, R2-D2

Or only greet the first name in the list


(greet (first names))
; Hello there, Alice

Maps

The second core collection is a map that is useful for storing key-value pairs. You can use anything you like as a key or value.

A simple person map could look like this

(def person 
  {"name" "Alice"
   "age" 20})

And a value can be accessed with the get function.

(get person "name") ;=>Alice

This works just fine, but often there is a better type you can use for keys and those are so called keywords. A keyword is, more or less, an identifier with special attributes and written with a leading colon, e.g. :name.

One of the best attributes of keywords is, that they can be used as lookup functions.

(def person 
  {:name "Alice"
   :age 20})

;This works
(get person :name) ;=>Alice

;But this is neater
(:name person) ;=Alice

Basic Control Flow

One of the simplest control flow construct in most languages is if-else.

In Clojure the generalised version looks like this.

(if test-expression
  then-expression
  else-expression)

Let's say you want to modify our greeting for anyone over the age of 50.

(defn build-greeting
  [person]
  (if (> (:age person) 50)
    (str "Good Evening, " (:name person))
    (str "Hey there, " (:name person))))

(build-greeting {:name "Andrew" :age 51})
=> "Good Evening, Andrew"

(build-greeting {:name "Alice" :age 20})
=> "Hey there, Alice"

Putting it together

Let's write a bit of code that prints greetings for a list of people.


(def people [{:name "Alice"
             :age 20}
            {:name "Andrew"
             :age 55}])

(defn build-greeting
  [person]
  (if (> (:age person) 50)
    (str "Good Evening, " (:name person))
    (str "Hey there, " (:name person))))

(defn greet-all
  [people]
  (for [person people]
    (let [greeting (build-greeting person)]
      (println greeting))))

(greet-all people)
;Hey there, Alice
;Good Evening, Andrew

Congrats! You now know the basics of Clojure.

If you want to learn more then I can recommend the following resources:

Official Getting Started Guide
Clojure for the Brave and True (Free Online Book)
Programming Clojure (Book)