Does Functional Programming Make Your Code Hard To Read?
Tags: functional, codequality, architecture
Published: 2020-10-14 14:45:38

**Work in software long enough and you’ll meet people that absolutely adore functional programming**, and the families of languages that self-select as “functional” – even if you might not realise what it means.

> “In computer science, functional programming is a programming paradigm where programs are constructed by applying and composing functions. It is a declarative programming paradigm in which function definitions are trees of expressions that each return a value, rather than a sequence of imperative statements which change the state of the program.”

From [Wikipedia](https://en.wikipedia.org/wiki/Functional_programming)

Originally coined as a term to describe an emerging family of languages – Haskell, LISP, Standard ML, and more recently applied to languages that follow in their spiritual footsteps like F# and Clojure – **functional programming languages are very much the mathematical end of programming**.

> “Functional programming languages are a class of languages designed to reflect the way people think mathematically, rather than reflecting the underlying machine. Functional languages are based on the lambda calculus, a simple model of computation, and have a solid theoretical foundation that allows one to reason formally about the programs written in them.”

From [“Functional Programming Languages”, Goldberg, Benjamin](https://dl.acm.org/doi/10.1145/234313.234414)

**This style of programming leads to applications that look very dissimilar to procedural or object-orientated code bases**, and it can be arresting if you’re not used to it as a style. 

Let’s take a look at an example of a program written in Clojure

```clj
user=> (if true
         (println "This is always printed")
         (println "This is never printed"))
```

and that same logic using C-like syntax

```js
if (user) {
    println("This is always printed");
} else {
    println("This is never printed")
}
```

These two programs do exactly the same thing but the way that control flows through the programs are different. **On smaller programs, this might not seem like a significant difference** in style, but as a program grows in size, **the way that control flow and state is managed between functional and procedural programming languages differs greatly**, with larger functional programming styled programs looking more like large compound equations than programs that you “step through”.

[Consider this example - a port of some of the original “Practical LISP” samples into Clojure](https://github.com/stuarthalloway/practical-cl-clojure/blob/master/src/pcl/chap_03.clj)

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/66kwl4tx027t3kprxx3c.png)
 
This is a good, and well factored sample.

**Any programming language that you don’t know will feel alien at first glance**, but consider the style of programming as you see it here – with functions composed as the unions of smaller, lower level functions.

With C-like languages (C, C++, Java, JavaScript, C#, Ruby, et al) being the dominant style of programming, if you’ve not seen functional code before, it at least appears different on a surface level.

# Why do people do this?

Ok, so just because it’s different, doesn’t make it bad 🖤

**Functional programming has got pretty popular because state management and mutability are hard, and cause bugs.**

What does that mean?

Well, if your program operates on some variables that it keeps in memory, it’s often quite difficult to keep track of which parts of your program are modifying your variables. As programs grow, this becomes and increasingly difficult and bug prone task.

**People that love functional programming often cite the “immutability” as one of its biggest benefits** – the simplest way of thinking about it, is that the functions that comprise of a functional program, can only modify data inside of them, and return new pieces of data. Any variables defined never escape their functions, and data passed to them don't have their state changed.

There’s a really nice benefit to this, in that **each individual function is easy to test, and reason about in isolation**, it really does help people build code with fewer bugs, and the bugs that are present often are contained only to single functions rather than sprawled across a codebase.

**Functional programs often remove your need to think about the global state of your program** as you’re writing it, and that’s a pleasant thing for a programmer.

# Let’s make everything functional!

So yes, some people reach that conclusion – and actually over the last decade or so, **there’s been a trend of functional syntactic constructs (that’s a mouthful) being introduced into non-functional languages.**

This probably started with C#’s Linq (Language Integrated Query – no, I don’t understand quite how they reached that acronym either), and continued with functional constructs in Kotlin (probably strongly inspired by C#), Swift, the general introduction of Lambdas and “functions as data” into a lot of programming languages, and more recently, hugely popularised by React.js being an implementation of [“functional reactive programming”](https://en.wikipedia.org/wiki/Functional_reactive_programming).

This subtle creep of functional style programming into more mainstream programming environments is interesting, because **more and more people have been exposed to this style of programming** without necessarily either studying its nuance, or having to buy into a whole ecosystem switch. 

It’s lead to codebases with “bits of functional” in them, and in some of the more extreme cases, the idea of a “functional core” – where core programming logic is expressed in a functional style, with more traditional procedural code written to deal with data persistence, and bits at the edges of the application.

As more hybrid-functional code exists in the real world, there’s an interesting antipattern that’s emerged – **functional code can be exceptionally difficult to comprehend and read.**

# But this isn’t the functional utopia you promised!

**Reading code is a distinctly different discipline to being able to write it.**

In fact, reading code is more important than writing it, because you spend more of your time reading code, than you do writing it, and functional programming suffers a lot at the hands of **“the head computing problem”.**

Because functional programming optimises for the legibility of reading a single function and understanding that all of its state is contained, what it’s far worse at is helping you comprehend the state of the entire application. That’s because **to understand the state of the entire application outside of running the code, you have to mentally maintain the combined state of the functions as you read.**

This isn’t particularly different to code written in a more linear procedural style, where as you read code, you imagine the state as it’s mutated, but with functional applications, you’re also trying to keep track of the flow of control through the functions as they are combined – **something that is presented linearly in a procedural language, as you follow the flow of control line-by-line.**

Holding these two things in your mind at once involves more cognitive load than just following the control flow through a file in a procedural codebase, where you’re just keeping track of some piece of state.

Proponents of functional programming would probably argue that this **comprehension complexity is counter balanced by how easy it is to test individual functions in a functional application**, as there’s no complicated state to manage or build up, and you can use a REPL to trivially inspect the “true value”. 

Reading difficulty spikes however, are the lived experience of many people trying to read functional code, especially in apps-with-functional-parts.

# What we really have is a context problem

This leads to an oft repeated trope that **"functional is good for small things and not large applications"** - you get the payoff of easy, state free comprehension without the cognitive dissonance of trying to comprehend both the detail of all the functions, and their orchestration at once.

As functional codebases get bigger, the number of small functions required to compose a full application increases, as does the corresponding cognitive load. Combine this with the “only small parts” design philosophy of many functional languages, and if you’re not careful about your application structure and file layout, you can end up with an application that is **somehow at once not brittle, but difficult to reason about.**

Compared to Object Oriented approaches – OO code is often utterly fixated on encapsulation, as that’s kind of the point – and **a strong focus on encapsulation pushes a codebase towards patterns of organisation and cohesion where related concepts are physically stored together**, in the same directories and files, providing a kind of sight-readable abstraction that is often easy to follow.

OO codebases are forced into some fairly default patterns of organisation, where related concepts tend to be captured in classes named after their functionality.

# But surely you can organise your code in functional languages?

**Absolutely!**

I suppose I just feel like OO code, and its focus on encapsulation, pushes code towards **being organised by default.** By comparison, FP code revels in its “small and autonomous” nature, perhaps a little to its detriment. 

It often is trying to be not be everything OO code is, and actually **a little bit of organisational hierarchy by theme and feature benefits all codebases in similar ways.**

I absolutely believe that FP code could be organised in a way that gives it the trivial sight-readability of "class-ical" software, combined with the state free comprehension benefits of "small FP codebases", but it definitely **isn’t the default stylistic choice in much of the FP code I’ve seen in industry.**

There’s a maths-ish purism in functional code that I find both beautiful, and distressing, all at once. But I don’t think it helps code comprehension.

I don’t think people look at maths equations and succeed at “head computing” them without worked examples, and in the same way, I think programmers often struggle to “head compute” functional programs without a REPL or step debugger, because the combined effects of the functions is opaque, and what a computer is good at.

I absolutely also appreciate that **some people love this exact same thing I find an un-expressive chore** with my preference for languages with more expressive and less constrained syntax

# We’re really talking about what the best abstraction for reading is

There's a truism here - and it's that **hierarchy and organisation of code is the weapon we have to combat cognitive load**, and different programming styles need to take advantage of it in different ways to feel intuitive.

**All abstractions have a cost and a benefit** – be it file and directory hierarchy, function organisation and naming, or classical encapsulation. **What fits and is excellent for one style of interaction with a codebase might not be the best way to approach it for another.**

When chatting about this on twitter, I received this rather revealing comment -

> “Whenever I've seen functional in the wild there is inevitably large chunks of logic embedded in 30-line statements that are impossible to grok. I think it is due to being such a natural way to write-as-you-think but without careful refactoring it is a cognitive nightmare”

[Stephen Roughley (@SteBobRoughley)](https://twitter.com/SteBobRoughley/status/1316288023261257728)

This is many peoples truth about encountering functional code in the wild, and I don’t think it has to be this way – it really shares **a lot in common with all the "write once read never" jokes thrown at Regular Expressions** - which are really just tiny compounded text matching functions.

# Does functional programming make your code hard to read then?

**Like everything in programming, “it depends”.**

**Functional code is beautiful, and side effect free**, but for it to be consumed by people that aren’t embedded in it, it often **needs to meet its audience half way** with good approaches to namespacing, file organisation, or other techniques to provide context to the reader so they feel like they can parse it on sight, rather than having to head compute its flow control.

**It’s easy to get swept away in the hubris of programming style without considering the consumers of the code**, and I think well organised functional codebases can be just as literate as a procedural program.

Functional parts of hybrid apps have a steeper challenge – to provide the reader with enough context during the switch from another programming style that they do not feel like they’re lost in myopic and finely grained functions with no structure.

**Beware cognitive load generators 🖤**