I really like ghc's comment style: all toplevel functions have a comment that describes usage and interface. Comments about implementation details and gotchas a

I really like ghc's comment style: all toplevel functions have a comment that describes usage and interface. Comments about implementation details and gotchas are floated out and referenced. https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle prepareRhs :: SimplEnv -> OutExpr -> SimplM (SimplEnv, OutExpr) -- Adds new floats to the env iff that allows us to return a good RHS prepareRhs env (Cast rhs co) -- Note [Float coercions] | (ty1, _ty2) <- coercionKind co -- Do *not* do this if rhs is unlifted , not (isUnLiftedType ty1) -- see Note [Float coercions (unlifted)] = do { (env', rhs') <- makeTrivial env rhs ; return (env', Cast rhs' co) } ...more equations for prepareRhs.... {- Note [Float coercions] ~~~~~~~~~~~~~~~~~~~~~~ When we find the binding x = e `cast` co we'd like to transform it to x' = e x = x' `cast` co -- A trivial binding There's a chance that e will be a constructor application or function, or something like that, so moving the coerion to the usage site may well cancel the coersions and lead to further optimisation. ...more stuff about coercion floating... -} ``