Rachel M. Carmena

Confused am I

2021-08-10T10:00:00+00:00

Some things can be prone to misunderstandings in this profession.

I think I didn’t realize about some of them until mentoring or receiving a question.

Continuous delivery and continuous deployment

The reason for this post.

I made this mistake during a presentation in 2013:

It could sound good: deployment on a staging environment and delivering when publishing on a production environment. No, I was wrong!

Continuous delivery should be the next step after continuous integration.

Continuous deployment just happens when the automated pipeline doesn’t stop on the staging environment: every change follows the entire pipeline to the production environment automatically.

Martin Fowler warned about this misunderstanding in Continuous Delivery.

401 and 403

Let’s see these HTTP status code that are used to represent errors on the client side:

401 Unauthorized
403 Forbidden

According to Hypertext Transfer Protocol (HTTP/1.1): Authentication:

The 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.

And Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content provides the description for the second one:

The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it.

The first one is related to authentication and the second one to authorization.

So I would have preferred 401 Failed Authentication and 403 Unauthorized.

406 and 415

Another possible misunderstanding with HTTP status codes on the client side:

406 Not Acceptable
415 Unsupported Media Type

According to Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content:

The 406 (Not Acceptable) status code indicates that the target resource does not have a current representation that would be acceptable to the user agent, according to the proactive negotiation header fields received in the request (Section 5.3), and the server is unwilling to supply a default representation.

The 415 (Unsupported Media Type) status code indicates that the origin server is refusing to service the request because the payload is in a format not supported by this method on the target resource.

I would have preferred 406 Unsupported Requested Media Type and 415 Unprocessable Request.

PUT and POST

PUT for updating, POST for creating is repeated like a mantra mistakenly.

PUT is also used for creating a new resource.

According to Hypertext Transfer Protocol - HTTP/1.1

The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. (…) In contrast, the URI in a PUT request identifies the entity enclosed with the request (…).

I also talked about it in RESTful thinking.

True and false on the command line

Look at this format of command:

$> <command> || <command-if-failure>

It works in this way:

If the first command finishes successfully (it returns true), a short-circuit happens and the second command won’t be executed.
If the first command fails (it returns false), the second command will be executed.

I realized about the following fact when explaining it:

The first command will return true if it finishes successfully.
When a command finishes successfully, it returns 0 exit code.
0 usually represents false.

Oh!

Shells include built-in commands like test which is playing in this case:

test returns a status of 0 (true) or 1 (false) depending on the evaluation of the conditional expression expr.

Finally:

$> <command-1> || <command-2>

would be equivalent to:

if <command-1>; then
    exit 0
else
    <command-2>
fi

On the other hand:

$> <command-1> && <command-2>

would be equivalent to:

if <command-1>; then
    <command-2>
fi

int is not the only integer data type

If a programming language provides a data type named int, it can be thought as the only integer data type. I realized this when mentoring a friend.

Let’s see the integer data types for different programming languages.

C provides int and a list of modifiers: short, long, unsigned, signed.

JVM-based programming languages like Java, Kotlin, and Scala provide these integer data types:

Integer data type	Range of values
`Byte`	From -2^7 to 2^7-1.
`Short`	From -2^15 to 2^15-1.
`Int`	From -2^31 to 2^31-1.
`Long`	From -2^63 to 2^63-1.

The data type names start with lowercase in Java.

What about CLI-based programming languages?

C# provides sbyte, byte, short, ushort, int, uint, long, ulong, nint, and nuint. More details in C#: Characteristics of the integral types.
F# provides byte, sbyte, int16, uint16, int, uint, int64, and uint64. More details in F#: Basic types.

I like the second one when the number of bits is added together int.

Let’s see Rust: i8, u8, i16, u16, i32, u32, i64, u64, i128, and u128. I love it! There is no room for error. More details in Rust: Integer types.

It’s also clear with Go: int, int8, int16, int32, int64, uint, uint8, uint16, uint32, and uint64. And byte is provided as an alias for uint8.

Code Smell: Primitive obsession

When I learned this code smell that appeared in Refactoring book, I received an example of a function with several String parameters:

The code was “polluted” with the choice of String type for those cases. What if it was necessary to use a different type?
The compiler couldn’t know if the arguments were being properly provided in a call. The meaning was just on the parameter names.
Those parameters had a related behavior that wasn’t being encapsulated.

The fix consisted on replacing String type with user-defined types for those parameters.

However, the code smell is called primitive obsession and String is not a primitive type:

The String class is not technically a primitive data type, but considering the special support given to it by the language, you’ll probably tend to think of it as such. Java: Primitive Data Types

The primitive types are Boolean, Byte, SByte, Int16, UInt16, Int32, UInt32, Int64, UInt64, IntPtr, UIntPtr, Char, Double, and Single. C#: Type.IsPrimitive Property

And this code smell is widely explained with String type. Even WikiWikiWeb relates primitive obsession with NoStrings.

On the other hand, this code smell could apply to any built-in type of a programming language. For instance, it could happen with a built-in collection type.

So I would have preferred the name obsession with built-in types, primitive or non-primitive.

DB views

CREATE VIEW doesn’t actually create a view as could be expected but a query that will be run every time it’s referrenced.

A view is actually created by CREATE MATERIALIZED VIEW, when supported by the DBMS, or other SQL sentences to materialize the view.

I would have preferred CREATE QUERY and CREATE VIEW, respectively.

Editing a comment or a message

Did this situation happen to you? Receiving a notification about a comment or a message, reading the text, thinking about it, opening the corresponding tool to answer and finding an entirely different text. The user edited the text after submitting it. And sometimes the message was edited more than 5 times afterwards.

What about this other one? Reading a message, coming back after a few minutes and that message was edited with a long list of items. There is no guarantee that those additional data will be read.

I’m always warning people around me about it.

Should communication tools allow us to edit the messages?

It seems they are doing their best in this sense:

Sending just one notification with the first version of the text.
Allowing an option to preview the text if it’s not a WYSIWYG editor.
Noting that the text was edited.
Allowing to see the editions history in some cases.

Could they do anything else to avoid these misunderstandings?

Maybe adding a warning message when a user is going to edit an existing message:

The initial message has already been read and notified. Please, consider writing a new message to avoid possible misunderstandings.

I think I understand that a tool like Twitter doesn’t allow to edit the submitted tweets:

A reply could be obsolete after editing a tweet.
The users that retweeted it or liked it might disagree with the updated content.
The updated content might not be read by those users.

However, it’s one of the most requested features.

Why not delete the tweet and create a new one?

Maybe too many steps: copy, delete, new, paste, edit the text, and submit.

Ok, why not add a Fix button to simplify that task?

The initial tweet will be deleted and a new tweet will be created when submitting it.

Just three steps: fix, edit the text, and submit. Internally, it would be like creating a new tweet from a template and keeping the id of the initial tweet to delete it. In other words, deleting and creating at the same time instead of updating.

You retweeted, liked or replied these fixed tweets:

Could the communication or project management tools follow the same idea?

Does this issue come from developers because we are always thinking about CRUD operations? What if one of them isn’t appropriate for a certain tool?

Rereading The Cathedral and The Bazaar

2021-07-16T10:00:00+00:00

A few weeks ago, I found a paper copy of the essay The Cathedral and The Bazaar by Eric S. Raymond from my first year of University degree, the subject Computing and Society. The essay had been published one year before and it would become a book one year later. It was very popular then.

So many years on, it deserved a rereading given what happened with The Mythical Man-Month.

I think it’s a recommended reading for anyone who wants to know more about the called bazaar style and the lessons learnt when applying it on an open-source product.

The essay is available on Eric S. Raymond’s website. I’m just including a few comments here.

Continuous delivery

I had been preaching the Unix gospel of small tools, rapid prototyping and evolutionary programming for years.

On the other hand, one chapter is entitled:

Release early, release often.

And one of the lessons in that chapter adds:

And listen to your customers.

Those things are widely mentioned nowadays. However, I’m wondering whether it would happen in 1997.

Make it work, make it right and make it fast

Eric explains how Linux started reusing code and ideas from Minix:

Eventually all the Minix code went away or was completely rewritten—but while it was there, it provided scaffolding for the infant that would eventually become Linux.

Find more details about make it work, make it right and make it fast.

Problem vs. Solution

I witnessed a lot of discussions in terms of the solution before having a clear understanding of the problem. Eric talks about the importance of understanding the problems (please, take a look at the essay to get more context about it):

you often don’t really understand the problem until after the first time you implement a solution

Often, the most striking and innovative solutions come from realizing that your concept of the problem was wrong.

Pygmalion effect

If you treat your beta-testers as if they’re your most valuable resource, they will respond by becoming your most valuable resource.

Simplicity

Don’t hesitate to throw away superannuated features when you can do it without loss of effectiveness.

When your code is getting both better and simpler, that is when you know it’s right.

Brooks’ law

The author tries to understand how an open-source product can be made by so many people because that fact contradicts Brooks’ law.

However, I find some differences between a team in a company and a community of an open-source product:

Target: People that are part of a community are usually users of the product.
Context: People that are part of a community decide freely their contributions.
Communication: Teams in a company usually have a biased view of a product. However, Eric explained how he dealt with the communication of the design decisions for the whole community.
Motivation: Sometimes it’s easier to find more recognition in a community than in a company.

References

Finally, it includes a small but interesting bibliography.

I would add Basics of the Unix Philosophy from the book The Art of Unix Programming by Eric S. Raymond. Some of the rules continue being discussed even nowadays.

Credit

Image by Majaranda from Pixabay

Awareness

2021-07-14T10:00:00+00:00

Reading books and articles, watching talks and documentary films, and listening to stories with critical thinking can help us to raise our awareness and to become better people personally and professionally.

Let’s see some books that helped me in this profession.

When learning

Pragmatic Thinking and Learning. Refactor your wetware by Andy Hunt

When programming

Understanding the Four Rules of Simple Design by Corey Haines
Working Effectively with Legacy Code by Michael C. Feathers
Design Patterns: Elements of Reusable Object-Oriented Software (known as GoF Patterns) by Erich Gamma, Ralph Johnson, John Vlissides, and Richard Helm
Code Complete. A practical handbook of software construction by Steve McConnell
Refactoring: Improving the Design of Existing Code by Martin Fowler
Clean Code by Robert C. Martin
The Art of Readable Code by Dustin Boswell and Trevor Foucher
Growing Object-Oriented Software, Guided by Tests (known as GooS book) by Steve Freeman and Nat Pryce
99 Bottles of OOP. A Practical Guide to Object-Oriented Design by Sandi Metz and Katrina Owen
The Coding Dojo Handbook. A practical guide to creating a space where good programmers can become great programmers by Emily Bache
What to Look for in a Code Review. Effective tips for reviewing code by Trisha Gee
The Mikado Method by Ola Ellnestam and Daniel Brolund
97 Things Every Programmer Should Know by Kevlin Henney
Effective Programming: More Than Writing Code by Jeff Atwood
Test Driven Development: By Example by Kent Beck
Fifty quick ideas to improve your tests by Gojko Adzic, David Evans, and Tom Roden
Domain Modeling Made Functional: Tackle Software Complexity with Domain-Driven Design and F# by Scott Wlaschin
Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions by Gregor Hohpe and Bobby Woolf

When versioning source code

Software Configuration Management Patterns: Effective Teamwork, Practical Integration by Stephen P. Berczuk and Brad Appleton

When creating products

The Cathedral and The Bazaar by Eric S. Raymond
Handbook of usability testing: how to plan, design, and conduct effective tests by Jeff Rubin and Dana Chisnell
Don’t make me think by Steve Krug
Pretotype it. Make sure you are building the right it before you build it right by Alberto Savoia

When releasing

From my point of view, an interesting book for any technical profile in this profession:

Release It! by Michael Nygard

When working in a team

The Mythical Man-Month by Fred Brooks
Peopleware by Tom DeMarco and Timothy R. Lister
Apprenticeship Patterns by Dave Hoover and Adewale Oshineye
The Software Craftsman: Professionalism, Pragmatism, Pride by Sandro Mancuso
The Pragmatic Programmer: From Journeyman to Master by David Thomas and Andrew Hunt
Extreme Programming Explained: Embrace Change by Kent Beck and Cynthia Andres
Quick glance at: Agile Anti-patterns by David Tanzer
Agile Technical Practices Distilled by Pedro Moreira Santos, Marco Consolaro, and Alessandro Di Gioia

An idea

If you have a book library in your company, add a poster with some advice:

No hurry.
Rereading is allowed.
Enjoy: if it’s not the right moment for a particular book, take another one and try it again later.
Take regular breaks for assimilation and reflection.
Share what you read (conversations, posts, small talks, drawings, etc).

Credit

Image by Speedy McVroom from Pixabay

A dream

2021-07-12T10:00:00+00:00

Have you tried to contribute with forums or any platform about Q&A?

New questions are appearing continuously.

They are endless lists of questions and questions.

After taking a look, some kinds of questions can be found:

Looking for an opinion.
Looking for a tool to do something.
Trying to understand a concept.
Knowing the reason for a message error and how to solve it.
Knowing how to do something with a programming language or a tool.

I understand the first two types of questions. However, what about the rest of the types?

What are the reasons for those questions?

They could be a signal about poor content in the official documentation.

Or maybe the official documentation is not properly organized or indexed and it’s not easy to find something.

Or perhaps the reason is our contemporary world where we’re getting used to achieving things immediately with “one-click” and there is no patience to read the documentation.

Anyway, what if …

The platform allows a way to provide one or more links when the answer can be found in the related documentation.
Otherwise, the platform would greatly recognize when someone provides the answer and at the same time makes a contribution to improve the related documentation.

Do you imagine how the technical documentation would improve?

Other things could happen afterwards: the use of technical documentation would increase and the number of questions would decrease.

If I think about the programming languages and tools that I learnt, I found it difficult to find “a single source of truth”. One of my dreams in this profession would be having better documentation (content, organization and indexation) and fewer questions on other platforms.

Corollary

It’s about “listening to the signals”, using the questions as feedback to identify improvement points.

For instance, I usually talk about “preparing a demo” or “preparing docs” moments. When doing it, I realize things that could be enhanced to make it easier to explain.

Credit

Image by Gerhard Bögner from Pixabay

Some topics in a nutshell

2021-06-07T10:00:00+00:00

This profession allows me to meet a lot of good people. One of them is the reason for this post.

Carlos Blé talked to me about his podcasts and the opportunity of participating with one-minute audios. That’s a good idea for me to think about the content previously and, at the same time, to make the effort to find the key points.

Here is the transcript of my audios.

Writing a blog

It wasn’t clear to me that having a blog was worthwhile because of thinking that posts could be obsolete very soon.

Not only technical posts could be out of date but also subjective posts because we evolve and can change our mind.

However, a blog helped me to organize ideas, to spend time reflecting on some topics and to spread things that had been useful when I shared them personally.

At last but not least, I also learn more from the received feedback.

Gender gap

If I think about myself and the reason why I’m working in tech, the answer is my mother, that is to say, having a female reference.

On the other hand, I’ve had bad experiences in this profession.

So, I think it could be useful to address these things:

Making women who were in this profession visible.
Taking care of women who are in this profession.

Test-driven development

I think that learning and practicing TDD can provide us more benefits beyond the TDD cycle.

It teaches us:

To think before writing code.
To divide the problems thanks to the step by step.
The importance of continuous improvement with the step of refactoring.
- That’s also a humbling experience because it’s really difficult to do something right at the first time.
- And it also helps us to progress more quickly because of the focus on making it work as the first step.
The value of tests because they are in the first place.

Therefore, regardless of working in a context where TDD can be difficult, I think that knowing TDD has much to offer.

Further reading: Be open-minded, my friend: TDD.

Code comments

I find empathy useful. That is, thinking about someone that didn’t live my circumstances or moments of taking some decisions. What comments would be useful for others?

Further reading: Be open-minded, my friend: Documentation.

Acknowledgments

Thank you so much again, Carlos Blé.

References

Carlos Blé’s podcasts (in Spanish)

Credit

Image by Krzysztof Niewolny from Pixabay

Not only source code smells

2020-12-29T10:00:00+00:00

I cannot forget that project…

I joined when it was almost one year old.

After a few days digging deeper into the product and trying to solve some issues, I proposed to start building the product from the beginning.

What?

Yes, I did it ;)

Oh, a young and daring person!!!

There wasn’t a trend to follow Agile methodologies then and it was the characteristic Waterfall project where all the decisions were made at the beginning before the product is built.

Oh, wait, that thing also happens in some “Agile” projects nowadays where all the decisions are made at the beginning to fill the backlog like there’s no tomorrow.

And backlog refinement sessions for those projects are extremely chaotic.

As Andy Hunt wrote in Pragmatic thinking and learning. Refactor your wetware:

Be comfortable with uncertainty. Agile software development embraces the idea of working with uncertainty. Early on, you don’t know what the project end date will really be. You’re not 100 percent certain which features will be present in the next iteration. You don’t know how many iterations there will be. And that’s perfectly OK: that’s the sort of uncertainty you want to be comfortable with. You’ll find answers as you go along, and by the end, everything will have been answered.

That’s one of the reasons why we talk about evolutionary architectures, for instance.

Please, let’s reflect about it. You’ll find a book about Agile Anti-Patterns at the end.

Let’s come back to the beginning of this story!

A lot of meetings were needed to defend my proposal.

I didn’t have too much professional experience then and several mates were asked to share their points of view.

By the end, the product was started from the beginning and we had a working product after a few weeks.

No merit.

I recognize that it’s easier to create a product when a huge amount of feedback exists. Likewise new products are created and work better than other competitors.

What happened before?

In summary, a lot of time had been invested on irrelevant features and they had been thought too complex. It’s known as accidental complexity.

At the same time, the most important features that gave meaning to the product, the core of the product, what defined the product, … those features hadn’t been taken care. Not only they didn’t work as expected for the client but also it was really difficult to make a change without breaking surprise things. Some Marie Kondo time was needed to organize them in a different way.

How could that project have been different?

I think that not only the source code has smells. All the things can have smells.

Some examples from that project:

When having a complex data model in an initial step: did we add extra features that the client didn’t request? Could it be reduced to start with a simpler step for an initial working product? Imagine those scenes where a person appears with a typewriter. That person doesn’t find a good story and starts a white paper several times. A new paper into the trash and starting again. We’re lucky because we’re working in a profession where it’s easy to delete things. However, we aren’t used to deleting what we write or draw but it grows and grows.
When having long discussions: why are they long? Every person is proposing a different solution. No agreements. It’s said that one’s ego plays in those discussions. I’m not sure about it. Maybe there are no agreements because any proposal could be right. Nobody knows it. What if we are discussing unknown things? What if we don’t have enough data to make a decision? Maybe, instead of egos, every person is looking at their crystal ball to look at the future and find the right solution. What if we wait for having more feedback to reach that point? What if we make a decision from the things that we really know right now? What would be the first small step now? We only know that … now so it’s necessary to … To do that, we can start … and then we’ll decide next steps.

Stop and think. Detect the smells. Detect what things are telling. Why this complex design? Why this long discussion?

Further knowledge

Book: Agile Anti-Patterns by David Tanzer - he talks about the product backlog bankruptcy among other interesting reflections - it’s also available in Spanish: Antipatrones del Desarrollo Ágil
Post and talk: El patadón pa’lante. Posponer decisiones by Eduardo Ferro
Post and talk: El arte del patadón pa’lante. Libro de recetas by Eduardo Ferro and Luis Artola
Book: Pragmatic thinking and learning. Refactor your wetware by Andy Hunt
Post: A possible next step
Post: Duplication, you’re welcome
Post: Coding-centered methodology

Credit

Image by Fearscare from Pixabay

Functional programming sparks joy 2

2019-08-20T10:00:00+00:00

Previous card: Functional programming sparks joy

Before adding more concepts, I would like to share a reflection.

I think that object-oriented programming and functional programming are such different paradigms that they are not comparable. However, I find a similar feeling.

When I discovered object-oriented design patterns, I realized that we weren’t doing anything special. Our problems were widespread.

The only difference between our development project and others could be the business domain.

What if we step forward? What if we can model the domain with two kinds of pieces?

When I was a child, I didn’t have LEGO bricks but TENTE with smaller pieces.

I still remember my helicopter of the forest brigade:

I assembled it and disassembled it hundreds of times.

However, it had more than two kinds of pieces.

What if we only need two kinds of pieces for creating software?

What if there is a branch of mathematics that tries to generalize things with two kinds of pieces and can be moved to computer programming?

I’m talking about category theory where a category is a collection of:

Objects
Relationships (also known as morphisms or arrows) between the objects

Functional programming is based on a category of sets where:

The objects are types (sets of values)
The arrows are functions

Just two kinds of pieces and the power of composition with all the abstractions defined and proved matematically.

As Bartosz Milewski wrote:

One of the important advantages of having a mathematical model for programming is that it’s possible to perform formal proofs of correctness of software.

Note: Imagine more than one category. And now, imagine arrows between categories:

From objects of a category to objects of another one
From arrows of a category to arrows of another one

Therefore, in functional programming:

The objects are types and functions

Remember that functions are first-class citizens and can be input and output as well.

It’s awesome the amount of things that can be built when “playing” with only two kinds of pieces.

Bartosz Milewski also wrote:

Category theory is full of simple but powerful ideas

Let’s review the other previous concepts (I already mentioned functions as first-class citizens):

If functions were impure, it would be very difficult to “play” with them and to compose with each other.
Mathematically, the common needs with types and functions are defined. We only have to use them, so we’ll program in a higher abstraction level.
Immutability is also essential to compose functions. Otherwise, the results couldn’t be anticipated.
Recursion will appear when defining types or functions.
Currying and partial application are some of the techniques to be able to compose functions (an output must match with the input of the following function).

Finally, let’s consider the business domain we are working on, the state machines, the processes, the transformations, the validations, … how do types and functions fit those needs? It seems they absolutely fit them.

About the examples

So far, I’ve used plain JavaScript and an example with Lodash library.

However, to continue explaining functional programming, I’ll include examples in PureScript, a strongly-typed functional programming language that compiles to JavaScript. It’s heavily influenced by Haskell.

I would have had a clear choice with other non-purely programming languages:

Arrow for Kotlin
Cats for Scala
Bow for Swift
VAVR for Java

I think it’s good to have libraries which add functional capabilities as a way of extending a language more quickly and with the support of the developers community.

However, I had a lot of alternatives in JavaScript:

Libraries: Lodash, Underscore, Rambda, etc.
Languages which compile to JavaScript: TypeScript, PureScript, Elm, ClojureScript, Reason, OCaml (the last two options thanks to BuckleScript), etc.

Why PureScript? I made the decision when trying to explain composite types:

Libraries such as Lodash or Underscore don’t allow to create sum types.
Ramda library provides Either, though it’s for doing an OR of function results.
I found a library for creating sum types: Daggy. However, this alternative involved making more decisions later.
TypeScript uses the pipe to represent the choice between basic types or the intersection of properties between objects.
I found composite types in Reason, though I didn’t find other capabilities.
What about the rest of options? I reviewed PureScript and it provided the characteristics I was looking for.

My only purpose is explaining functional programming. PureScript is only a choice for it.

Note: Sometimes we think about selecting only one programming language (as I did here). However, for a real software product, we could choose different programming languages according to the needs. There are a lot of languages which compile to JavaScript, which run under JVM or which run under the CLR, among other options.

Declaration and definition

In PureScript, as in Haskell, it’s a good practice to provide type annotations as documentation though compiler is able to infer them.

The function type annotation is known as the function declaration. Its notation is influenced by Hindley-Milner type system and it has the following parts:

Function name
:: (= “is of type” or “has the type of”)
Function type:
- Input type
- ->
- Output type

The function definition is where the function is actually defined.

For instance, the declaration and definition of add function:

add :: Int -> Int -> Int
add x y = x + y

Note: As in other languages such as Haskell or F#, all functions are considered curried. So the add function is really:

add :: Int -> (Int -> Int)

It takes an integer (the first operand) and returns a function. That function takes the other integer (the second operand) and returns the sum.

This is transparent to us because the function definition and the use work like a function of 2 parameters.

Composite types

Types can be combined to create a new type.

The new type is also known as an algebraic data type (ADT).

Why algebraic? Because we can “play” with them on equations and symbols (I didn’t cover it here although it’s fun!).

There are two common kinds of composite types:

Product types
Sum types

Let’s see what they are and some examples and then I’ll explain a curiosity that can be useful to understand the reason of their names.

Product types

This is an example of the creation of a new type with the product of two types:

data Money = Money {
    amount   :: Amount,
    currency :: Currency
}

Its values will contain both a value of type Amount and a value of type Currency.

Why product? Think about the number of different values for that type: the product of the number of different values of the type Amount and the number of different values of the type Currency.

Sum types

This is an example of the creation of a new type with the sum of two types:

data SendingMethod 
    = Email String
    | Address { street  :: String, 
                city    :: String, 
                country :: String }

The new type SendingMethod represents a choice between Email and Address.

The values of this new type will contain a value of type Email or a value of type Address.

Why sum? Think about the number of different values for that type: the sum of the number of different values of the type Email and the number of different values of the type Address.

Note: I only included examples of combining two types for simplicity though there is no limit.

Note: Initially I used type composition as section title. It wasn't right because it could be confused with composition from function composition.

Pattern matching

In functional programming, pattern matching is based on constructors as patterns.

Given a value, it can be disassembled down to parts that were used to construct it.

This is a powerful tool to make decisions according to types:

showSendingMethod :: SendingMethod -> String
showSendingMethod sendingMethod = 
    case sendingMethod of
        Email email -> "Sent by mail to: " <> email
        Address address -> "Sent to an address"

Some composite types

Tuple

Tuple is an example of product type that represents a pair of values.

It’s defined in the module Data.Tuple of PureScript:

data Tuple a b = Tuple a b

where:

The lowercase letters a and b represent any type
The first Tuple is the type constructor
The second Tuple is the value constructor

Let’s see an example:

pair :: Tuple String String
pair = Tuple "spam" "eggs"

where:

The type constructor Tuple is used in the declaration: pair is of type Tuple String String
The value constructor Tuple is used in the definition: the value of pair is Tuple "spam" "eggs"

It’s known as Pair in other languages.

Maybe

Maybe is an example of sum type that is used to define optional values.

It’s defined in the module Data.Maybe of PureScript:

data Maybe a = Nothing | Just a

where:

The lowercase letter a represents any type
Maybe is the type constructor

Maybe of a type can represent one of these options:

A missing value: Nothing
The presence of a value of that type: Just a

Let’s see an example of use:

showTheValue :: Maybe Number -> String
showTheValue value =
    case value of
        Nothing -> "There is no value"
        Just value' -> "The value is: " <> toString value'

It’s known as Option in other languages.

Either

Either is another example of sum type and it’s commonly use for error handling.

It’s defined in the module Data.Either of PureScript:

data Either a b = Left a | Right b

where:

The lowercase letters a and b represent any type
Either is the type constructor

Either represents the choice between 2 types of values where:

Left is used to carry an error value
Right is used to carry a success value

Let’s see an example of use:

showTheValue :: Either String Number -> String
showTheValue value =
    case value of
        Left value' -> "Error: " <> value'
        Right value' -> "The value is: " <> toString value'

Some guidelines

Making things explicit

It can be said that functional programming is based on making things explicit as much as possible.

For instance, let’s think about Maybe.

If a function returns an integer, a missing value is not expected.

With Maybe, it can be made explicit that the function returns an integer or not.

Making illegal states unrepresentable

This is a design guideline by Yaron Minsky.

Let’s see an example. Imagine that we have a type Course with this content:

data Course = Course {
    title           :: String,
    started         :: Boolean,
    lastInteraction :: Maybe Date
}

There is an illegal state that can be representable: started is false and lastInteraction has a date.

For instance, that illegal state could be avoided with a sum type:

data Course 
    = StartedCourse { title :: String, lastInteraction :: Date }
    | UnstartedCourse { title :: String }

Note: This design guideline reminds me another one that has a wider application. It was formulated by Scott Meyers:

Make interfaces easy to use correctly and hard to use incorrectly.

Interfaces occur at the highest level of abstraction (user interfaces), at the lowest (function interfaces), and at levels in between (class interfaces, library interfaces, etc.)

Typeclasses

A typeclass defines a family of types that support a common interface

Typeclasses are useful to define concepts like monoids, functors, applicative and monads for all the types or types constructors, respectively.

And then, it’s possible to create instances of those typeclasses for concrete types or types constructors.

I include more details about it in following sections.

Monoids

A monoid is useful to explain how the values of a type are combined.

Let’s see some examples with known types.

For instance, natural numbers:

They could be combined with addition, for instance.
Zero could be the starting point and then, add each number.
Given 3 numbers, the result with be the same for these operations:
- The addition of the first 2 numbers is added with the third number.
- The first number is added with the addition of the other 2 numbers.

Or strings:

They could be combined with concatenation.
An empty string could be the starting point and then, concatenate each string.
Given 3 strings, the result with be the same for these operations:
- The concatenation of the first 2 strings is concatenated with the third string.
- The first string is concatenated with the concatenation of the other 2 strings.

How to express it in an easy way?

Monoids to the rescue!

Read the following definition together with the previous examples.

A monoid is a type with a binary operation (2 elements). That operation has the following properties:

It has a neutral element (identity)
It’s associative

Did you identify each part of the definition in the previous examples?

Note: I included examples with simple and known types. However, think about any kind of type and the need to define how the values of a type are combined.

Typeclass for monoids

Let’s see how to abstract the concept of monoid for any type and then, how to define it for concrete types.

In Haskell, the typeclass for a monoid includes the neutral element (called mempty) and the binary operation (called mappend):

class Monoid m where
    mempty :: m
    mappend :: m -> m -> m

However, PureScript has a previous abstraction and includes the binary operation in Semigroup typeclass:

class Semigroup a where
    append :: a -> a -> a

So Monoid typeclass extends the Semigroup typeclass with the neutral element:

class Semigroup m <= Monoid m where
    mempty :: m

That’s the abstraction. Now, for instance, how to define the way of combining strings?

The monoid for strings in PureScript (modules Data.Semigroup and Data.Monoid, respectively):

instance semigroupString :: Semigroup String where
    append = concatString

instance monoidString :: Monoid String where
    mempty = ""

The binary operation is concatenation and the neutral element is the empty string.

In this way, it’s possible to combine all the strings from an array into a single string when using the append and mempty defined for strings:

greeting :: String
greeting = foldl append mempty ["Hello,", " ", "world!"]
-- "Hello, world!"

Note: foldl folds the array from the left. In this case, the result would be the same with foldr.

Functors

You already know a functor!!

A functor is a type constructor which provides a mapping operation.

Which functor do you know for sure?

Array is a functor which provides the map function.

Let’s remember the included example in the first part (plain JavaScript):

const square = number => Math.pow(number, 2);

const numbers = [2, 5, 8];
numbers.map(square); // [4, 25, 64]

The same example in PureScript:

square :: Int -> Int
square number = pow number 2

numbers = [2, 5, 8] :: Array Int

logShow (map square numbers)
-- [4,25,64]

or using an infix function application (as an operator between the two arguments):

logShow (square `map` numbers)
-- [4,25,64]

logShow (square <$> numbers)
-- [4,25,64]

Graphically:

It’s said that:

The map function allows the function square to be lifted over an array
Or just, the map function lifts the square function

How to form a functor

Following the definition, a functor can be formed by:

A type constructor
A mapping function

For instance, the functor formed by:

The type constructor Maybe (in this case, from String to Maybe String)
The following fmap function:
- From a function (String -> String)
- To a function (Maybe String -> Maybe String)

repeat :: String -> String
repeat aString = aString <> aString

fmap :: (String -> String) -> Maybe String -> Maybe String
fmap f value =
    case value of
        Nothing -> Nothing
        Just value' -> Just (f value')

message :: Maybe String
message = fmap repeat (Just " bla ")
-- (Just " bla  bla ")

Graphically:

In this example, the fmap function lifts the repeat function.

Note: For simplicity in the examples, I included functions like square and repeat which have the same type for input and output. However, that condition is not necessary.

Note: What's the purpose of functors? Let's remember the need of composing functions and the need of adapting the input and output to compose them. We've already seen some tools for it and a functor is another one. We'll see more of them in the next sections.

Typeclass for functors

Let’s see how to abstract the concept of functor for any type constructor and then, how to define it for a concrete type constructor.

The typeclass for a functor appears in Data.Functor module:

class Functor f where
    map :: forall a b. (a -> b) -> f a -> f b

Following the previous example, the functor for Maybe is already defined in Data.Maybe module:

instance functorMaybe :: Functor Maybe where
    map fn (Just x) = Just (fn x)
    map _  _        = Nothing

So it can be used to get the same result than before with less code:

repeat :: String -> String
repeat aString = aString <> aString

logShow (map repeat (Just " bla "))
-- (Just " bla  bla ")

or using an infix function application (as an operator between the two arguments):

logShow (repeat `map` (Just " bla "))
-- (Just " bla  bla ")

logShow (repeat <$> (Just " bla "))
-- (Just " bla  bla ")

Functor composition

So far I’ve included examples of Array functor and Maybe functor separately.

What if there are more than one functor?

What if we want to apply the repeat function into a Maybe (Array String)?

Firstly, we use the mapping function of Array and then, the mapping function of Maybe over the result.

In other words, the mapping functions are composed (operator >>>):

logShow ((map >>> map) repeat (Just [" bla ", " ha "]))
-- (Just [" bla  bla "," ha  ha "])

Applicative

There are a lot of things about applicative. I include the basic applicative abstraction also known as an applicative functor.

An applicative functor is an step further than a functor.

Let’s see what happens if we have a function with more than one parameter.

For instance:

fullName :: String -> String -> String
fullName name surname = name <> " " <> surname

Functions are curried by default in PureScript, so in this case: the input is a String and the output is another function String -> String.

What happens if instead of two strings for name and surname we have Maybe String for each of them?

With map from functorMaybe, we get another function from Maybe String to Maybe (String -> String).

In other words, the function String -> String is wrapped with the type constructor Maybe.

How can we continue?

How can we get another function from Maybe String to Maybe String?

apply to the rescue!

In PureScript, the applicative for Maybe is already defined so it’s possible to use apply with that kind of type constructor:

logShow (apply (map fullName (Just "Rachel")) (Just "M. Carmena"))
-- (Just "Rachel M. Carmena")

logShow (apply (map fullName (Just "Rachel")) Nothing)
-- Nothing

or using an infix function application (in this case, <*> is the equivalent to apply):

logShow (fullName <$> Just "Rachel" <*> Just "M. Carmena")
-- (Just "Rachel M. Carmena")

logShow (fullName <$> Just "Rachel" <*> Nothing)
-- Nothing

Therefore, if we have a function with more than two parameters, we’d use <$> (map) for the first parameter and then <*> (apply) for the rest of parameters.

Another powerful tool to compose functions. Think about other type constructors like Either, form validations, etc.

Finally, after the examples, it could be easier to understand the difference between map from functors and apply from applicative functors:

map :: forall a b. (a -> b) -> f a -> f b

apply :: forall a b. f (a -> b) -> f a -> f b

Both get the same result though map transforms a function and apply transforms a function which is wrapped.

Note: In this section, I didn't include the formal definition of applicative functors in PureScript and the corresponding instance for Maybe. They can be found in the modules Control.Apply, Control.Applicative and Data.Maybe. There are also instances for Either, Array, List, etc.

Monad

Let’s see what happens if we have a getUser function from a String value to a Maybe User value:

and we don’t have a String value available to be provided to the function but a Maybe String value.

Then, we can think about the Maybe functor to have a Maybe String value as an input:

However, the result will be a Maybe (Maybe User) value.

How can we get just a Maybe User value?

Flattening Maybe (Maybe User) into Maybe User:

Both operations are considered together by bind from a monad:

bind :: forall a b. m a -> (a -> m b) -> m b

Following the example of the getUser function, it’s possible to get a Maybe User value from a Maybe String value, because the instance of Monad for Maybe is already available in PureScript:

user :: Maybe User
user = bind (Just "12345") getUser

or using an infix function application (in this case, >>= is the equivalent to bind):

user :: Maybe User
user = (Just "12345") >>= getUser

It’s said that monads are useful to chain dependent functions in series:

Note: The ability to wrap a value to a context is done by the pure function from a functor. For instance, from a String value to a Maybe String value.

Further knowledge

Talk: Truth about Types by Bartosz Milewski
Post: The Science Behind Functional Programming by Rafa Paradela
Post: Functors, Applicatives, And Monads In Pictures by Aditya Bhargava
Online book: Structure and Interpretation of Computer Programs by Harold Abelson, Gerald Jay Sussman and Julie Sussman
Playlist: MIT 6.001 Structure and Interpretation, 1986 by Hal Abelson and Gerald Jay Sussman
Online book: Category Theory for Programmers by Bartosz Milewski
Specification: Fantasy Land Algebra
Typeclassopedia
Book: Haskell Programming from first principles by Julie Moronuki and Christopher Allen

Credit

Image by Anthony Jarrin from Pixabay

Functional programming sparks joy

2019-08-05T10:00:00+00:00

Motivation

The title comes from Marie Kondo’s recommendation about feeling if an item sparks joy to keep it with you or to discard it.

When I heard about functional programming I decided to continue learning about it. Why? Let’s see some reasons.

Introduction

I agree with Scott Wlaschin when he says that functional programming is not scary but unfamiliar. It has a mathematical basis and is full of new concepts.

However, the more you know about functional programming and working examples, the more advantages you notice in the paradigm.

Which programming language am I going to use for the examples? JavaScript. It’s not a purely functional programming language like Haskell but multi-paradigm, so it’s suitable for talking about it.

Moreover, I think it can be interesting to start practicing with a known and non-purely functional programming language before moving to another one.

Pure functions

One of the objectives is to have pure functions.

A pure function works as follows:

It takes an input.
It works with that input and no more. It doesn’t access the outside in order to get more things, neither changes it the outside.
It returns an output.

This image appears in my mind:

So it has these properties:

It returns the same output from the same input.
It has no side effects.
It’s referentially transparent: a call can be replaced by the output for the present input. It’s not necessary to execute the function to preserve the semantics of the program.

Referential transparency is a simple and powerful concept: Can I replace this function call by its result without altering the program behaviour? Why? Can it be simplified? Would it be necessary to compute that function call every time? Could some results be memoized?

Declarative programming

My Dutch uncle who is now retired and always worked very near developers told me:

I’ve heard that one of the problems in software development is that source code includes a lot of details and we should program at a higher abstraction level.

I think it’s useful to explain this section.

Functional programming is declarative: it doesn’t reveal details of implementation.

For example, imagine that we have the following function:

const isEven = number => (number % 2 === 0);

and we want to know if an array only contains even numbers:

const onlyContainsEvenNumbers = array => {
    for (let index = 0; index < array.length; index++) {
        if (!isEven(array[index])) {
            return false;
        }
    }
    return true;
}

const numbers = [2, 4, 8, 10, 20, 11];
onlyContainsEvenNumbers(numbers); // false

The onlyContainsEvenNumbers function is an example of imperative programming: it includes a lot of details to indicate how to get the goal.

However, compare it with this alternative where an expression is used to describe what to get:

const numbers = [2, 4, 8, 10, 20, 11];
numbers.every(number => isEven(number)); // false

// Following the pointfree style:
numbers.every(isEven); // false

If fewer details are given then: less prone to error and easier to read.

In this case, less tests would be needed because the every function is known to work as expected.

Note: The "point" of pointfree style is not . but a point on a space. f(x) can be read as "the value of f at point x". So pointfree style consists on not specifying the parameters to avoid redundancy.

Note: The function isEven is an example of predicate, a function that returns a boolean value.

Immutability

How many times have you seen a call that modifies the arguments when only an output is expected as a result of that call?

What if the immutability is ensured?

For example, we have a function to calculate the square:

const square = number => Math.pow(number, 2);

and we want to calculate the array of squares from an array of numbers:

const calculateSquares = array => {
    for (let index = 0; index < array.length; index++) {
        array[index] = square(array[index]);
    }
    return array;
}

const numbers = [2, 5, 8];
calculateSquares(numbers); // [4, 25, 64]

Not only a lot of details are given again but also the numbers array is mutated to [4, 25, 64].

However, let’s see the following code:

const numbers = [2, 5, 8];
numbers.map(square); // [4, 25, 64]

In this case, we get the same result and the numbers array remains with the same content at the end.

This is only an example. Immutability is pursued beyond arguments.

The consequences of immutability are testable and parallelizable code.

Note: The map function doesn't only return an array with the same type of items. It accepts a function from the original type to any type.

Note: Moore's law established that the number of transistors on integrated circuits would double every two years. However, the limit was reached for the year 2002. Later, multicore processors appeared to keep the speed increases. Parallelizable code is the only way to take advantage of them.

On the other hand, we can find impure functions in JavaScript like sort:

> const numbers = [100, 1, 8, 25]; 
undefined
> numbers.sort()
[ 1, 100, 25, 8 ]
> numbers
[ 1, 100, 25, 8 ]
> numbers.sort((a, b) => (a - b))
[ 1, 8, 25, 100 ]
> numbers
[ 1, 8, 25, 100 ]

The numbers array is mutated.

That impure function could be wrapped into a pure function:

const sortArray = (array, compareFunction) => {
    const arrayCopy = array.slice();
    return arrayCopy.sort(compareFunction); 
}

> const numbers = [100, 1, 8, 25];
undefined
> sortArray(numbers, (a, b) => (a - b));
[ 1, 8, 25, 100 ]
> numbers
[100, 1, 8, 25]

In production code, I would think about these questions: Where do I need to sort an array? Do I have a lot of functions with an array as a parameter? Should I have to create a new data type?

Note: However, programs usually change the outside world. In that case, what if mutations are isolated in a specific part of the source code?

Higher-order functions

In JavaScript, a function is a first-class citizen:

It can be the argument to another function.
It can be the output of another function.

A higher-order function is a function that takes another function as an argument or returns another function (or both).

I included examples of every and map so far. Let’s see examples with filter and reduce:

const isEven = number => (number % 2 === 0);

const numbers = [4, 2, 11, 20, 7];
numbers.filter(isEven); // [4, 2, 20]

const add = (accum, value) => accum + value;

const numbers = [4, 10, 1, -10];
numbers.reduce(add); // 5

// Good habit: indicating an initial value
numbers.reduce(add, 0); // 5

The power of having functions as first-class citizens and creating higher-order functions promotes the separation of responsibilities and readability.

Note: When reduce doesn't include an initial value (second parameter), the first item from the array is used as the initial value for the accumulator and skipped. In the included example, it's not necessary to indicate an initial value, because the first item can be used as the initial value and skipped. However, I talked about a good habit to avoid problems with empty lists.

Note: Some programming languages differentiate between reduce (without providing an initial value) and fold (providing an initial value). Others have just fold for both options.

Function composition

Functions can be composed into a new one.

When following the definition of composing two functions, the functions appear from right to left because the output of the first function is the input of the following one.

For example, the sumOfSquares function:

const square = array => array.map(number => Math.pow(number, 2));
const sum = array => array.reduce((accum, value) => (accum + value), 0);

const sumOfSquares = numbers => sum(square(numbers));

const numbers = [2, 4];
sumOfSquares(numbers); // 20

However, there are other two ways of composing functions where the functions appear from left to right: pipe or chain.

For example, let’s see the sumOfSquares function as a pipe:

const square = array => array.map(number => Math.pow(number, 2));
const sum = array => array.reduce((accum, value) => (accum + value), 0);
const pipe = (f, g) => (...args) => g(f(...args));

const sumOfSquares = numbers => pipe(square, sum)(numbers);

// Following the pointfree style:
const sumOfSquares = pipe(square, sum);

or as a chain:

const square = number => Math.pow(number, 2);
const sum = (accum, value) => (accum + value);

const sumOfSquares = numbers => numbers.map(square)
                                       .reduce(sum, 0);

Note: I only included examples of composing two functions for simplicity though there is no limit.

Tail recursive functions

In functional programming, iteration is usually programmed with recursion so it’s important to control the growth of the call stack.

How? Reusing the call frame instead of adding a new one.

It’s known as tail call optimization or proper tail calls.

Given a recursive function, that optimization is possible if it calls itself as its last action. That is, it’s a tail recursive function.

Let’s see a non-tail recursive function:

const factorial = number =>
    number === 0
        ? 1
        : number * factorial(number - 1);

The stack trace for factorial(4):

factorial(4)
* factorial(3)
* (3 * factorial(2))
* (3 * (2 * factorial(1)))
* (3 * (2 * (1 * factorial(0))))
* (3 * (2 * (1 * 1)))
* (3 * (2 * 1))
* (3 * 2)
* 6
24

On the other hand, the same function as a tail recursive function:

const factorial = (number, accumulator = 1) =>
    number === 0
        ? accumulator
        : factorial(number - 1, accumulator * number);

The stack trace for factorial(4):

factorial(4)
factorial(3, 4)
factorial(2, 12)
factorial(1, 24)
factorial(0, 24)
24

That’s the reason why it’s possible to reuse the call frame: there is no need to remember the previous calls.

However, the last factorial function could be called with an argument for the accumulator parameter from the beginning:

const WRONG_ARGUMENT = 5;

factorial(4, WRONG_ARGUMENT); // 120

So let’s prevent that error and create an alternative with only one parameter and a closure:

const factorial = number => {
    const fact = (number, accumulator = 1) =>
        number === 0
            ? accumulator
            : fact(number - 1, accumulator * number);
    return fact(number);
}

Currying

Currying consists of converting a function with several parameters into nested unary functions (unary = one parameter).

For example, we have this function with two parameters:

const log = (level, message) => `[${level}] ${message}`;

log("ERROR", "Undefined variable"); // "[ERROR] Undefined variable"
log("INFO", "New post created");    // "[INFO] New post created"

It could be transformed into two nested functions:

const log = level => message => `[${level}] ${message}`;

const logError = log("ERROR");
const logInfo = log("INFO");

logError("Undefined variable"); // "[ERROR] Undefined variable"
logInfo("New post created");    // "[INFO] New post created"

Notice the improvement in readability: logError, logInfo.

Moreover, the need of writing "ERROR" and "INFO" every single time disappears.

I tried to write my own curry function to convert any function into those nested unary functions automatically. The original function can only be called when having all the arguments, so I needed to accumulate the arguments recursively (arity = number of arguments expected by a function):

const curry = fn => {
    const arity = fn.length;
    const _curry = (...args) => 
        args.length === arity
            ? fn(...args)
            : arg => _curry(...args, arg);
    return _curry();
}

Following the previous example:

const log = (level, message) => `[${level}] ${message}`;

const curriedLog = curry(log);

const logError = curriedLog("ERROR");
const logInfo = curriedLog("INFO");

logError("Undefined variable"); // "[ERROR] Undefined variable"
logInfo("New post created");    // "[INFO] New post created"

Note: My own version doesn't work like the curry function that can be found in libraries such as Lodash or Ramda which add more capabilities.

Note: In languages such as Haskell or F#, all functions are considered curried.

Partial application

Partial application consists of doing a projection: specifying only some arguments in function application, producing another function with the remaining parameters.

For example, let’s play with the partial function from Lodash, using an underscore for the unknown arguments:

var _ = require('lodash');
const { log } = console;

const greet = (name, place, message) =>
    `Hello ${name} from ${place}! ${message}`;

const greetFromWonderland = 
    _.partial(greet, _, "Wonderland", _);

const greetFromWonderlandWithWish =
    _.partial(greetFromWonderland, _, "Have a good day!");

log(greetFromWonderlandWithWish("Mike"));
// Hello Mike from Wonderland! Have a good day!

Note: Beyond the included examples, currying and partial application are useful to be able to compose functions.

Another mindset

Last but not least, all of these things (and many more!) make us to think in a different way:

Fewer details. We program at a higher abstraction level.
It forces ourselves to separate responsibilities in building blocks and then to combine them.
Side effects under control. We are more aware of mutations.
I didn’t talk about functional data types but I could say that Primitive Obsession smell can be eradicated with this paradigm.

A new mindset is needed to embrace functional programming.

Vocabulary

Some words which weren’t used here although they can be useful to understand other articles:

Domain: Set of possible inputs to a given function.
Codomain: Set of possible outputs to a given function (the prefix “co” is used to refer to the opposite).
Total function (vs. partial function): It returns a valid output for every possible input. They are just known as functions.
Polymorphic function: In functional programming, polymorphism is also known as parametric polymorphism. A polymorphic function operates on values without depending on their type. It’s valid for any type.

Next card

Functional programming sparks joy 2

Further knowledge

Post: The Free Lunch Is Over: A Fundamental Turn Toward Concurrency in Software by Herb Sutter
Talk: Tail Call Optimization: The Musical!! by Anjana Vakil & Natalia Margolis
Talk (Spanish): Better types = fewer tests by Raúl Raja
Talk: Domain Modeling Made Functional by Scott Wlaschin
Article: Why Functional Programming Matters by John Hughes
Reflection: Functional programming is deep by Eric Normand
Articles: PragPub Magazine #38

Acknowledgments

Special thanks to these old colleagues:

Christian Panadero for giving me the first master classes about functional programming and category theory. They were the best ice-breaker classes.
Carlos Morera de la Chica for being the best travel companion together with Christian during several editions of Lambda World Conference.
Richard Wild for providing me a lot of reflection moments with his series about The Functional Style.

And thanks to:

Eduardo Sebastian for his pull request to fix some typos.
Christophe Riolo Uusivaara for his valuable feedback about tail call optimization. It’s not only related to recursive functions.

Credit

Image by Anke Sundermeier from Pixabay

The usefulness of small ‘crazy’ ideas

2019-07-25T12:00:00+00:00

Space invader

It wasn’t the first time I met someone who was worried about GitHub contributions panel.

A friend of mine was too much worried about it. Too much… and my words weren’t useful.

I needed to come up with something to make an impact on him.

So I programmed a small script to create a space invader in an empty year or whatever he liked.

For example, I have a space invader in 2016:

See the full script and all the details in Space Invader GitHub repository.

Result: It worked! It made him reflect.

Note: When sharing it in Twitter, someone mentioned this project: gitfiti. I didn't know it though I understand my idea wasn't unique. The goal is very similar although the way to get it is different and it's based on GIT_COMMITTER_DATE to change the date.

Saying goodbye to an awesome colleague

A colleague was going to leave the company and he had been a very important person for all of us.

I then created a Slack channel as a tribute to write all the things we had learnt from him.

That Slack channel was very beautiful and I wanted him to have it forever.

So I programmed this small tool to create a PDF from a Slack channel based on Slack API and Latex.

Result: He loved the idea.

I was helping as an event organizer and it was necessary to schedule tens of tweets.

I was added to Tweetdeck and I thought that I could simulate the user actions to schedule all the tweets after being logged in.

So I opened the Web Console and I created this function to schedule a tweet at 10:30 by default:

const scheduleTweet = (message, day, goToNextMonth) => {
  $(".tweet-button").click();

  $(".js-compose-text").value = message;
  $(".js-compose-text").dispatchEvent(new InputEvent("change"));

  $(".js-schedule-button").click();
  $("#amPm").click();  // depends on the current time
  $("#scheduled-hour").value = 10;
  $("#scheduled-minute").value = 30;
  if (goToNextMonth) {
    $("#next-month").click();
  }
  $("a[href='#".concat(day).concat("']:not(.caldisabled):not(.caloff)")).click();

  $(".js-send-button").click();
}

And then I only had to program a script to get a list as follows:

setTimeout(scheduleTweet, 3000, '...', 30, 0);
setTimeout(scheduleTweet, 6000, '...', 31, 0);
setTimeout(scheduleTweet, 9000, '...', 1, 1);
setTimeout(scheduleTweet, 12000, '...', 2, 0);
setTimeout(scheduleTweet, 15000, '...', 3, 0);
setTimeout(scheduleTweet, 18000, '...', 4, 0);
setTimeout(scheduleTweet, 21000, '...', 5, 0);
setTimeout(scheduleTweet, 24000, '...', 6, 0);
setTimeout(scheduleTweet, 27000, '...', 7, 0);
setTimeout(scheduleTweet, 30000, '...', 8, 0);
setTimeout(scheduleTweet, 33000, '...', 9, 0);
setTimeout(scheduleTweet, 36000, '...', 10, 0);
...

I wrote that list in the Web Console and after 3 seconds I saw how all the tweets were scheduled in the same way I was doing that work with the web interface (maybe it wasn’t necessary to wait for 3 seconds between them).

Result: I had all the tweets scheduled after a couple of minutes.

Beyond post-it notes

I was going to join another team in a client as a software craftsperson (a mix between a developer and a technical coach). It was a special situation and I wished to have a good start.

I organized a meeting a few days before joining as a first contact to meet each other. I wanted to know their concerns and wanted them to have an idea of all the things that we could get together.

I tried to come up with something different to the use of post-it notes in order to have a pleasant meeting and to promote the participation.

Why not to write the questions and the list of things I wanted to talk about in a long paper roll?

Oh no, that’s a crazy idea!

Why not?

I didn’t have time to buy a paper roll so I made it from five Din A4 sheets of paper.

I cut each sheet of paper in three pieces and I joined them with a little of adhesive transparent tape.

My thoughts again. Oh no, that’s a crazy idea!

Why not?

I wrote all the things in the new paper roll, leaving room to take notes.

I was ready for the meeting.

And the time of the meeting arrived.

I unrolled the paper.

More than four meters of paper.

Surprised looks.

As we progressed on every issue, I cut the corresponding piece of paper.

And I placed it in one of the two stacks of paper: done or to review (with additional notes).

The paper roll was more and more short.

Result: There was an agreeable atmosphere during the meeting and I got a lot of information about the team and their concerns.

Corollary: It's said that sometimes we create things from our memories. My maternal grandfather stored things from his old tailoring. A lot of paper rolls for the purchase receipts, among others. I played with those rolls a lot of times when I was a child.

RESTful thinking

2019-07-23T10:00:00+00:00

Motivation

Working for (old) banking institutions was another world for me. I remember that the only way to integrate with their software systems was based on file transfer and it was necessary to agree on filenames, formats, directories, time schedules and dependencies.

In other projects, the integration was based on the database (DB): sometimes sharing the same DB and other times synchronizing DBs.

However, the most common way of integration was through SOAP services. We received a huge WSDL file and we used a tool to create the client from that file. Maybe I could say that it was a smell: a lot of details in a single file and a tool to hide the complexity of creating a web service consumer.

Then, I knew other two ways of integration which are still commonly used: RESTful services and messaging systems. Regarding the latter, I’m referring to message queues and message brokers (I write this clarification because web services also exchange messages).

Nowadays, it seems that everybody uses RESTful services although SOAP services are still used in certain contexts for enterprise services.

Despite that, is REST (Representational State Transfer) architectural style really known? Do the currently called RESTful services really use the power of the Web architecture?

Introduction

I think that there are so many differences between SOAP and RESTful services that maybe they are not comparable.

SOAP services expose stateful operations which implement some business logic. The contract is specified via WSDL, the message format is only XML, there isn’t a standard failure management and SOAP messages are only sent via HTTP POST, among others.

On the other hand, RESTful services expose resources through data. Those data can be represented in several formats (not only XML) and they are exchanged through a stateless communication. These services can be consumed by any client in a lightweight way.

In short, RESTful services follow the benefits of the Web architecture while SOAP services only use the transport protocol.

Let’s see some characteristics of RESTful services.

RESTful Web Services

Stateless

The service provider and consumers exchange representations of resources.

The consumer includes all the information necessary to understand the request.

The provider doesn’t answer with an explicit application state.

This characteristic promotes the simplicity, low coupling and scalability.

Resources

I mentioned resources. What are they?

According to Roy Thomas Fielding:

Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on.

Mark Massé differentiates four resource archetypes: document (singular noun), collection (plural noun), store (plural noun) and controller (verb or verb phrase in lower camel case). The last one would be used for actions that don’t correspond with the known HTTP methods.

Intuitive URIs

URIs don’t encode operations. URIs identify resources and the purpose of a service can be inferred from the URI.

Sometimes it’s interesting to pursue the opposite for security reasons. In that case it would be necessary to have a mapping between URIs and resource handlers. We’ll see a way to provide the semantic to a hard-to-guess URI later.

On the other hand, URIs can be specified through templates as follows:

http://my-card-game.com/decks/{deck-id}

Where {deck-id} can be replaced by a deck identifier.

It’s an easy way to understand, validate or create URIs.

Only one URI for identifying a resource regardless of the representation format

URIs don’t have an extension according to the representation format of the resource. For example: .json for a JSON representation or .xml for a XML representation.

A resource is identified by only one URI while the desired representation format or media type is indicated in the Accept request header.

Following the example, it’d be used, respectively:

Accept: application/json
Accept: application/xml

HTTP methods as actions

Resources can be manipulated through HTTP methods as actions.

We are responsible to keep the semantics of these HTTP methods according to the specification:

GET for retrieving the details of a resource. The request message doesn’t include a body. Use the query component of the URI (?) to include filters.
HEAD when the consumer only wants to receive the HTTP headers. The request message doesn’t include a body.
OPTIONS for checking which HTTP methods a resource supports.
DELETE for deleting a resource.
PUT for creating a resource or updating the state of a resource.
PATCH is an alternative to PUT in order to apply partial modifications to a resource. The PATCH method requests a set of changes (called “patch document”) on the resource identified by the Request-URI.
POST. Let’s see…

As Sam Ruby and Leonard Richardson wrote:

POST is commonly used to create subordinate resources: resources that exist in relation to some other “parent” resource.

Why not use PUT to create those resources?

The difference between PUT and POST is this: the client uses PUT when it’s in charge of deciding which URI the new resource should have. The client uses POST when the server is in charge of deciding which URI the new resource should have. (…) The POST method is a way of creating a new resource without the client having to know its exact URI. In most cases the client only needs to know the URI of a “parent” or “factory” resource.

In summary:

Create a new resource: HTTP PUT to a new URI, or HTTP POST to an existing URI.

Modify an existing resource: HTTP PUT to an existing URI.

For example, Amazon S3 API:

Note: There is a common misunderstanding about PUT and POST. In the wrong way, it's said: PUT for updating and POST for creating. Nowadays, when remembering that I made the same mistake, I don't understand the reason why it's easy to embrace that belief. There isn't a clear relationship between the meaning of the words "put", "update", "post" and "create". Maybe our mind deceives us because of put and update ;)

On the other hand, it’s our responsibility to meet the HTTP method properties according to the specification:

Safe: If the defined semantic is essentially read-only and a state change on the server is not expected. The GET, HEAD and OPTIONS methods are safe.
Idempotent: If the intended effect on the server of multiple identical requests is the same as the effect for a single request. The PUT, DELETE and safe request methods are idempotent.
Cacheable: When responses to a method are allowed to be stored for reuse. Mainly GET and HEAD methods are cacheable.

Note: There is also a common misunderstanding about an idempotent HTTP method. It's focused on the intended effect on the server. That's the reason why GET is idempotent although multiple GETs of the same URI can generate a response with different data.

HTTP status codes as response codes

It’s not necessary to define error types or error codes. HTTP status codes are used as response codes.

Let’s see some of them.

Successful operations (2xx status codes):

200 OK: Nonspecific success.
201 Created: Successful resource creation.
202 Accepted: It’s used for asynchronous operations. The server accepts the request and provides an URI to get the result later.
204 No Content: When the server has fulfilled the request but does not need to return a payload (PUT, POST or GET with an empty representation). It’s also used to indicate a successful response for a DELETE request. If the response must indicate the final state of the deleted resource: 200 OK and a full payload with the resource representation.

Errors on the client side (4xx status codes):

400 Bad Request: It’s used when returning the payload with the same received data plus a comment about the reason why it’s a bad request.
401 Unauthorized: If there is an issue with the client’s credentials (wrong or missing).
403 Forbidden: When the access is not allowed regardless of the right credentials.
404 Not Found: When the client requests a resource that doesn’t exist. It’s also used in some responses in order not to give too many details to consumers when thinking about security.
405 Method Not Allowed: The response must include the Allow header in order to know which HTTP action or actions are allowed.
409 Conflict: For example, a requested update cannot be executed.
411 Length Required: If Content-Length header in a request is missing, the service cannot determine if it’s a huge payload to cause a DoS attack.

Errors on the server side (5xx status codes):

500 Internal Server Error
503 Service Unavailable: It’s used with a Retry-After header.

HTTP status codes are useful to manage situations as a change of a resource URI. In that case, it can be communicated when sending the HTTP status code 301 Moved Permanently or 303 See Other in the response (3xx status codes = redirection).

Entity tag value for managing the changes of the state of a resource over its lifetime

The server can associate a string token with a certain state of a resource (like a version number): an entity tag value which will appear in the ETag header of a response.

Then, the client can indicate that entity tag value in a request header to condition the request to a particular state of the resource.

The conditional request headers are:

If-Match: <entity_tag_value> = apply the request if the resource hasn’t changed since the last received representation
If-None-Match: <entity_tag_value> = apply the request if the resource has changed since the last received representation

Other uses:

If-Match: * = apply the request if the resource exists
If-None-Match: * = apply the request if the resource doesn’t exist

A related HTTP status code: 412 Precondition Failed

Advantages:

Services perform less computation because they know the ETag to execute the request. Higher response time from services.
Avoiding errors because of managing an out-of-sync resource.
It may be cheaper for a service to compare ETag values rather than to generate a representation.
Preventing race conditions between clients.

Disadvantages:

The generation of the entity tag value in the server can be computationally expensive. It’s important to select a cheap way to generate it from the state of the resource and to be unique.

Beyond CRUD services

As URIs identify resources, there is a trend to create CRUD services. In that case, there is a high coupling with consumers as well as the services are like an interface to operate with the DB.

Let’s go beyond…

Links in the resource state representation

Resource state representation can include links to related resources or next business steps.

This is the basis of HATEOAS (Hypermedia As The Engine Of Application State) from REST architectural style.

The consumer receives a resource representation with links and one of them will be chosen as the next step.

In this way, we can model state transitions or business processes when transiting links between resources.

The consumer doesn’t have to depend on a big number of static URI templates or contracts. It’s enough with a few URIs that act as entry points.

Therefore, the provider can evolve the internal business rules more easily.

Note: Although we are used to representing relations between entities through identifiers (think about the foreign key in a database), we don't use identifiers but URIs to address the related resources in the resource representation. If we use identifiers, the consumer would have to know how to build the URI of the related resource and it's better if that knowledge is retained in the service provider.

One step further

If we are using a JSON representation, an example of link could follow this format:

"link": {
    "uri": "...",
    "rel": "..."
}

The URI is together with another link, rel attribute, where there is information about the meaning or purpose of the link.

How could that information be understood by machines? How could computer-to-computer interactions be possible without the need of a human interaction to interpret and to consume it?

That’s one of the goals of Semantic Web Technology, machine learning, machine-processable formats, directed labeled graphs, ontontologies to represent knowledge, etc.

Note: Links can also be used to split the resource representation into different parts. The decisions about which data to show in the representation and which data will be obtained when following a link are based on the size of the payload, performance and cacheability, among others.

Other things

Security

HTTPS provides confidentiality and integrity on the transport layer. Besides that, we need authentication and authorization management:

Authentication to identify the consumer (for example, OpenID).
Authorization to control what a consumer can do (for example, OAuth).

Postel’s Law

It’s said that it’s followed by robust services:

Be conservative in what you do; be liberal in what you accept from others.

In other words: be strict about the generated resource representations in responses, be permissive about the received representations in requests.

This law made me think a lot and I don’t know if that lesson is really useful in all cases. I’m thinking about browsers that render content although it’s wrong (lack of ending tags, lack of accessibility data, etc) or, in general, standards that are not followed.

Maybe that permissiveness is helping us to progress very quickly though we are accumulating debt because of it.

I remember when my old colleague Erik Torres talked about responsible freedom.

Lots of thoughts…

Update: I think my reflection here addressed a different personal concern with the lack of constraints. This law is useful for robustness when preventing breaking changes.

Resources

Specifications

API documentation

Initiatives

Tools

Note: The use of API or Web API doesn't refer only to those which conform to the REST architectural style (RESTful APIs).