Four Tips for New Haskell Programmers

The Haskell programming language is widely considered to have a fairly steep learning curve--at least compared with mainstream languages.  In my experience with Haskell and specifically helping newcomers I've noticed a few common issues that seem to come up again and again.  Some of these issues might be more avoidable if the Haskell community did a better job communicating them.  Four points I have noticed are:
  1. Read Haddock API docs
  2. Pay attention to type class instances
  3. Learn about kinds
  4. Learn monad transformers

Read Haddock API Docs

I mention this point at the risk of stating the obvious.  If you are going to become a proficient Haskell programmer, it's absolutely essential that you get used to reading the API docs for the packages you use.  I often hear newcomers ask for tutorials demonstrating how to use packages.  Our community would definitely be better off with tutorials for every package, but it would also be better if newcomers would pay more attention to the API docs.  Now I know you're probably thinking, "yeah, but most packages are poorly documented."  That is true, but Haskell's type signatures tell you a lot more about a function than other languages.  For instance, consider the following example:

readChan :: Chan a -> IO a

A Chan is essentially a queue.  You can put values in and get them out in FIFO order.  When you are trying to understand the above function, one of the first things you might wonder about it is whether it blocks or not.  But if you think about it a little more, you'll realize that this function has to block.  If it didn't block, then there might not be a value and there would be no way to return something of type a (because Haskell has no null pointers).  A non-blocking version would have to have a type signature like this:

tryReadChan :: Chan -> IO (Maybe a)

So even with no prose documentation added at all, you can still learn a lot from the type signatures.  This is more significant in Haskell than other languages because of Haskell's purity and its strong type system.  Also, I would recommend that you bookmark the url "http://hackage.haskell.org/package/".  Actually, better yet, type it into your web browser frequently so it is the first thing given to you by the autocorrect when you start typing "hack...".  Once you auto-complete that url, you can just type the name of the package you are looking for and you'll immediately get to the most recent API docs for that package.  It's way faster than hitting control-f and searching through the package list on that page.

Also, bookmark http://www.haskell.org/ghc/docs/latest/html/libraries/index.html because it has links to documentation for the core libraries.

Pay Attention to Type Class Instances

I can't emphasize this point enough.  One of the most common questions I get from beginners is how to run an IO function in some random monad.  This information is trivially visible in the API docs, but for some reason beginners never seem to notice.  Take for example the Snap monad.  Go ahead, click that link and look at the documentation.  The clue that you can run IO actions inside that monad is tucked away near the end of the "Instances" block.  It's one little innocuous line MonadIO Snap.  Newcomers might not be familiar with MonadIO, but if they click the link they'll see that it defines one function liftIO :: IO a -> m a that converts any function in the IO monad to a function in the current m monad.  Those instance lines contain a treasure trove of information.  Don't neglect them.

Learn About Kinds

In Haskell all values have a type.  Analogously, all types have a kind.  This topic is often not brought up until later, but I feel that understanding kinds gives beginners a big advantage in understanding type signatures.  I'm not going to go into it in detail here, but I think it's an important concept that is too often ignored.

Learn About Monad Transformers

This is another one of those topics that is often put off until later.  When I was learning monads, I distinctly remember getting the impression that monad transformers were a much more complicated beast and that I didn't need to learn about them at that time.  But when I finally did learn about monad transformers a lot of things became clearer for me.  Also, monad transformers are used all the time in real world applications.  Transformers are a much simpler concept than monads, especially if you know about kinds.  There's no reason not to learn them at the same time.

Comments

Anonymous said…
I would add: don't hesitate to read the source code for library functions you don't understand. In Java, C++, etc, the source code is of limited use in understanding a library because you typically have to wade through a maze of classes, interfaces, state mutations, etc, to have any idea what's going on in there. Haskell code, by contrast, tends to be quite compact and readable.

This is especially important given the generally poor state of Haskell library docs. I don't understand why the Haskell elite think a haddock file consisting of only type signatures counts as documentation. And not too get too ranty, but until library developers learn to take some care in showing cookbook-style examples showing how to use a library, a lot of people are going to continue giving up in frustration when trying to use haskell to do e.g. simple signal processing, XML processing, graphics work, and so on.
April 16, 2012 at 1:52 PM
Anonymous said…
Although it's true the type signatures give you a really big clue how individual functions operate, they're next to useless in providing clues on how to assemble the various functions into a working whole. When approaching a new library to attempt to solve some concrete problem (say, load and parse an XML file, and then find a particular node) knowing where to even start can often be a daunting task. To begin with it's often unclear which module to start looking in, particularly with the "main" module often simply re-exporting every other module in the library. When you do finally find a promising looking module you'll often find a function that looks like it will do exactly what you want, but it either takes some argument you're unsure how to construct, or else it operates inside of some monad that it's unclear how to run an instance of (or worse yet, some kind of newtype wrapper around a monad transformer stack that you only find out about after digging through the source code of the library).

TL;DR; version, type signatures are good if you want to know "what does this function do", but proper documentation is necessary to answer "how do I use this library".
December 10, 2012 at 1:41 PM
mightybyte said…
Orclev,

I both agree and disagree. Individual type signatures obviously don't tell you how to put things together. But collectively they do. Hackage provides a pretty decent interface for hyperlinking around the libraries you would need. Yes, in some cases library authors do need to put in some effort, but even when they don't the type signatures alone are still useable. I will concede that it takes some time to learn how to do this effectively. But in my experience it makes learning new libraries WAY easier than my experience has been with dynamic languages.
December 10, 2012 at 1:50 PM
Anonymous said…
@mightybyte

I can agree that given two libraries of equal documentation quality, one for Haskell, one for some other dynamic language, the Haskell one will tend to be much easier to understand how to use. For simpler libraries (particularly ones without any complicated state machinery) the types alone are sufficient. However for larger libraries type signatures are no replacement for proper documentation. It's extremely difficult to hold an entire library in your head, particularly one you're using for the very first time. At the bare minimum a one line example (preferably from inside of IO showing all the state setup) can go a long way towards making a library more accessible by pointing out at least one of the entry points.

Once you've got that initial function to start building from, following the type signatures can usually get you the rest of the way, but finding that first function shouldn't be a game of where's Waldo, and that's where proper documentation comes in.

Another thing documentation can be a major help with is exploring the more advanced but esoteric aspects of a library. Most libraries will have a handful of functions that exist specifically to handle unusual edge cases, and properly documenting what those are and how to deal with them can be a huge time saver for your users.

So, while it's true that the powerful type system in Haskell allows for much stronger inference about a function given only its type signature (and name), that's still no excuse for the generally shoddy documentation that you see in the Haskell community.

By all means encourage people to learn to "follow the types", but please don't use that as an excuse to forgo proper documentation on libraries. As the first commenter on here pointed out, a lot of users give up in frustration either before learning how to infer properties from type signatures, or else when confronted by a library with a particularly pernicious set of type signatures (I myself have skipped over certain libraries because they required more effort to understand than one of their alternatives).
December 10, 2012 at 4:25 PM
mightybyte said…
@Orclev

> but please don't use that as an excuse to forgo proper documentation on libraries.

I wasn't.
December 10, 2012 at 4:36 PM
Post a Comment

Popular posts from this blog

A Hopefully Fair and Useful Comparison of Haskell Web Frameworks

Recently there has been a lot of discussion and questions about the differences between the big three Haskell web frameworks: Happstack, Yesod, and Snap. Different pieces of the answer have been discussed in a number of places. In this post, I'd like to try to give a more complete comparison. Hopefully it will be relatively unbiased, but without being so watered down that it is useless. I've succeeded if you can't tell which framework I'm a major contributor to based solely on the text of this post. Happstack First, up is Happstack , the oldest of the three with original commit history as early as February, 2005. Happstack used to be called HAppS . It was primarily composed of a web server based on lazy IO, a fairly radical (for the time) in-memory persistence approach for storing and versioning native Haskell data types, and a library called IxSet for making it easier to use this state system with relational data access patterns. I've heard a number of pe...
Read more

Setting Up A Private Nix Cache

I recently went through the process of setting up a private Nix binary cache. It was not obvious to me how to go about it at first, so I thought I would document what I did here. There are a few different ways of going about this that might be appropriate in one situation or another, but I’ll just describe the one I ended up using. I need to serve a cache for proprietary code, so I ended up using a cache served via SSH. Setting up the server For my cache server I’m using an Amazon EC2 instance with NixOS. It’s pretty easy to create these using the public NixOS 18.03 AMI. I ended up using a t2.medium with 1 TB of storage, but the jury is still out on the ideal tradeoff of specs and cost for our purposes. YMMV. The NixOS AMI puts the SSH credentials in the root user, so log in like this: ssh -i /path/to/your/key.pem root@nixcache.example.com To get your new NixOS machine working as an SSH binary cache there are two things you need to do: generate a signing key and turn on cache serv...
Read more

Dependent Types are a Runtime Maybe

Awhile back I was discussing dependent types with someone and we ended up concluding that dependent types can always be replaced by a runtime Maybe.  This seemed to me then (and still does today) as a fairly surprising and provocative conclusion.  So I thought I'd put the idea out there and see what people think. Let's look at a few examples that are commonly used to illustrate dependent types: Vectors of length N Matrices of size m x n Sorted lists Height-balanced trees (trees where the height of subtrees differ by at most one) The argument is roughly as follows.  All of these examples ultimately boil down to enforcing some kind of constraint on some data types.  The more powerful your dependent type system, the more rich and expressive will be the constraints that you can enforce.  If we take this thought experiment to its logical conclusion, we end up with a dependent type system that allows us to enforce any constraint that can be computed. The important rea...
Read more