Explaining code equals knowledge sharing
Both teachers and developers use similar tools that help them share knowledge and/or explain code to their peers: paper drawings, whiteboards, PowerPoint presentations, vigorous arm movements, … you name it. Explaining code especially becomes a standardised item on the to-do list for the developer who prefers Function Oriented Programming (FP) over Object Oriented Programming (OOP).
Functional Programming (FP) took some explaining
I was somewhat disappointed in Java 7 Object Oriented programming. Surely, I could do it but that wasn’t how I wanted to code.
An object-based application in Java is based on declaring classes, creating objects from them and interacting between these objects.
Edureka! Object Oriented Programming – Java OOPs Concepts With Examples
So I started taking a course of functional programming (FP), learning Haskell basics in particular. It blew my mind. It was like being rocketed to Mars and learning everything anew. Ever since then I always thought that functional programming was the way to go. With a strong emphasis on purity of functions, dealing only with inputs and outputs whenever possible. Add a more descriptive way of doing computations, like using map versus a classical for loop and I’m completely sold.
In short, I had an aha-erlebnis: this is how I wanted to program.
In short, I had an aha-erlebniz. This is how I want to program!
In computer science, functional programming is a programming paradigm—a style of building the structure and elements of computer programs—that treats computation as the evaluation of mathematical functions and avoids changing-state and mutable data.
Wikipedia – Functional Programming
Before long I was juggling with function references in production code, and my colleagues hated it.
My colleagues hated my overly complex higher order functions
In my mind Recursive functions are not devilish producers of stack overflow exceptions. They can be a nice way to reason about programs. Higher order functions remove obfuscating boilerplate code in my humble opinion. My conviction did not come without consequences.
For example:
I had considered the Object Oriented (OO) way of decomposing a common Email class, but didn’t want to create many child classes. And that laziness cost me in clarity. I then wrote a complex handler higher order function on which my colleagues commented it was overly complex. On another occasion, some of my team members were confounded when I presented monads. To my surprise even those colleagues that anyone would objectively consider great developers found my code hard to understand.
We aren’t all as used to read code like that. It’s very difficult to understand.
My colleagues during code review
In conclusion: sure, I understood the code — nicely factoring out the common behavior in a function and passing that along. The code passed review, albeit receiving a weakly phrased critique. We didn’t want to lose any more time on that code and never looked back. Right now I wish I had.
Clarity is in the eye of the reader as much as beauty is in the eye of the beholder. And for my colleagues, the advanced concepts of functional programming quickly move out of that space.
So I quickly learned that there is a flip side: my colleagues weren’t always pleased with my style and “is this code self-explaining” became a standard item on my checklist before commits.
Finding the perfect balance between FP and OOP
I went back to the drawing board. Seeking for a clearer way of coding. A way that had to be more Object Oriented Programming (OOP), and less advanced Functional Programming (FP).
I’ve found a way to combine the — in my eyes — academic way of coding with the Java Virtual Machine (JVM) and all of the existing Java frameworks when I started formalizing my Scala knowledge. Taking the coursera course taught by Martin Odersky helped me to reframe my insights about the true combination of OOP and FP that Scala promotes. Since then this has been making its way into all mainstream languages — looking for that sweet spot between both paradigms.
I could use Functional Programming (FP) in practice and write nice code. Afterwards I had similarly joyous feelings when writing Java 8 streams code on projects I worked on.
In short, I started writing more OO code again, forcing myself to reacquaint with the art of OO. Just like most production-used programming languages, moving to a hybrid model that combines FP with OOP enabled best of both worlds and helped to aim for maximum clarity by dividing the problem space using OOP and the functionality using FP-concepts.
Take your peers’ starting point into account when explaining code
What I think I learned here in all my experiences is that you program for your colleagues. So the biggest advice developers can take from teachers is to keep things simple and take the starting point of a new developer into account.
In teacher formation you take the “beginsituatie” (dutch for “starting point”) into account when preparing for a course. That starting point is the expected set of knowledge and skills a developer (or student) needs to join your team (or class).
There are many technical skills popping up in your mind right now if you start pondering the question about what this starting point is for a developer, but hold it for a minute. I primarily mean how much of the business domain does the developer need to grasp to understand the system? Only then should you be thinking about terminology used in the code that needs explaining.
For example: are some composite calculations separated into smaller methods with meaningful names? Or are there these magical equation-ish statements tucked away in your codebase? Seasoned developers can more quickly forget about these things because their experience helps them to feel comfortable, but fresh developers need to learn. This is why being aware of the initial situation matters for both teachers and developers.
In conclusion: keep it simple and communicate!
You start out with your students/colleagues at some specific level, the starting point. At the starting point, it’s your job to get everyone at your level of knowledge and understanding. This is where the skill of a teacher comes in when explaining code.
Resources
- Object Oriented Programming (OOP)
- Functional Programming (FP)
- Coursera: Functional Program Design in Scala
- Scala
- “Beginsituatie” (dutch)
Hire an Expert Developer
Become an Expert Developer
