How, precisely, can we improve?

[Michal Terepeta]

Hi,

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
biggest
barrier for involvement for me is understanding the code (i.e., it’s a
complex
and large project).

Yes, Phab/Trac are an additional hassle, but for me not really that
significant
compared to the task of understanding what’s happening in the compiler
(although
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:
learning
  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
  `compiler/`.

- Ability to use `Outputable` instances with `Debug.Trace.trace` works
  surprisingly well. (Although mapping the output from `Outputable` back to
AST
  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
what’s
  the current status, is not always easy.  Also, it's not always easy to
find...
  Maybe documentation on the wiki could follow the directory/module
structure
  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
contributors.
  But this can be quite challenging for newcomers and unfortunately
explanations
  can be spread around across code, papers, etc. (e.g., it took me a while
to
  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
then
  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
ago,
  I wasted half an hour just because of a weird formatting of a do-block!
[3]
  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
state
  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. :-)

Cheers,
Michal


[1] https://ghc.haskell.org/trac/ghc/wiki/Commentary/Compiler/GeneratedCode

[2] https://github.com/tibbe/haskell-style-guide

[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: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20160926/20bcba34/attachment.html>