How, precisely, can we improve?

Michal Terepeta michal.terepeta at
Mon Sep 26 19:28:41 UTC 2016


I just wanted to add a few things from a perspective of a GHC newbie. Not
everything is a concrete proposal on how to improve things, but I hope it's
still useful.

First of all, a big +1 on what Moritz said - having everything in one system
like Phab would be really nice.

But I also want to second what Richard Fung said in another thread - the
barrier for involvement for me is understanding the code (i.e., it’s a
and large project).

Yes, Phab/Trac are an additional hassle, but for me not really that
compared to the task of understanding what’s happening in the compiler
small, localized contributions might be an exception here!).

So let's start with the things that I personally find helpful :-)

- Some of the documentation on Trac is great (e.g., "I know kung fu:
  STG by example" [1] is amazing!)

- “Notes” in the code (especially the ones that give concrete examples of
how we
  want to transform the code and why!) are super useful.

- Modify & compile cycle is super quick when using `make 1` or `make 2` in

- Ability to use `Outputable` instances with `Debug.Trace.trace` works
  surprisingly well. (Although mapping the output from `Outputable` back to
  can be non-trivial!)

Things that I find problematic:

- Some of the documentation on Trac is outdated or appears to be a "work in
  progress" but hasn't been updated in years.  So getting a clear idea of
  the current status, is not always easy.  Also, it's not always easy to
  Maybe documentation on the wiki could follow the directory/module
  more closely? (also making it more obvious when it gets out of date)

- There's a lot of knowledge that seems to be assumed from the reader. I'm
  guessing that most of the key concepts are obvious for regular
  But this can be quite challenging for newcomers and unfortunately
  can be spread around across code, papers, etc. (e.g., it took me a while
  understand what's the deal with "join-points" and "let-no-escape").
  Not sure how to solve this, except for having better documentation...

- Validate often fails. Workaround: run `./validate` without a patch and
  with the patch. If there are no differences, it's probably unrelated.
  It'd be much nicer if this wasn't necessary.

- Coding style. I personally do find it quite distracting to jump between
  modules that are using a different style (often wildly different!). It
  definitely does slow me down.
  And bad formatting can be actually pretty harmful, e.g., not that long
  I wasted half an hour just because of a weird formatting of a do-block!
  Finally, note that coding style is pretty much a standard today, so many
  people expect it in well maintained codebases and might see the current
  as "messy".  (And perceptions do matter sometimes!)
  The solution here would be to adopt an official coding style (e.g., [2]).

Anyway, I hope you find this useful. :-)




[3] I was looking at a do-block like this:

do { A
   ; …
   ; B

where it seems that both A and B should always execute. Except that, after
closer examination, there were two blocks present!

do { A
   ; …
     foobar $ \x -> do
   ; B

They were just indented to make it appear as if there was just one! :-(
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the ghc-devs mailing list