3 ms·

I don't know exactly what it does, but I do know it only uses basic mathematical operations, it's just a formula. I also know it doesn't do any logging, or "lau

I don't know exactly what it does, but I do know it only uses basic mathematical operations, it's just a formula. I also know it doesn't do any logging, or "launch nukes", and that it is thread safe. You're never given only the type signature however, you also will have the source code. It's very likely that foo is no more complicated than something like: foo :: Num a => a -> a foo n = n * 42 + 1 If foo is as complicated as that, then a sentence or two explaining what it's purpose is would be helpful; explaining the "why" of such an odd function would be good. The documentation probably can't say "what" foo does any more clearly than the source code however. If the function is reasonably named, like: double :: Num a => a -> a double n = n + n then having some documentation that says "Doubles the given number" isn't going to add much value, and might become out of sync with the actual code. I appreciate that all the Haskell documentation I have ever encountered has a links to the source code throughout. Aside: When I look at the definition of an unknown function in Haskell, I feel like I'm at the top of an hierarchy. The unknown function may be comprised of other unknown functions, but the entire structure of what is happening is present. I know what all the variables are, etc. When I look at the definition of an unknown object-oriented function I often find myself in the middle of an inheritance stack with implicit behaviors and variables being inherited from above, and unknown functions being called below, and it's more confusing in my opinion.

rpglover64 10y ago
> it's just a formula. I also know it doesn't do any logging, or "launch nukes", and that it is thread safe. So the type claims. Without looking at the implementation or using `-XSafeHaskell`, you don't know if there's an `unsafePerformIO` call lurking. /pedantry
- Buttons840 10y ago
  Even if the function had documentation that said "this function does not have side effects" it could still have side effects. So within the context of this thread, type signatures vs hand written documentation, I would say your point is a +0 for hand written documentation. Both type signatures and hand written documentation can lie.
14113 10y ago
I guess the counterexample would be library functions that look like: foo :: (BarMonad m, BazApplicative b) => ConfigurationStructure t -> (b -> m t) -> [b] -> t You can figure out a little of what it does, but how that fits into the application it supports, and what exactly it should be used for is non trivial. Haskell programmers (whose numbers I count myself amongst) saying that "the types are the documentation" is like expecting someone to build a lego model from the picture on the box, and saying "well the studs are the documentation of how the pieces fit together". It's correct, but it misses all the nuance of how the functions should be composed, not just how they can be composed.

rpglover64 10y ago

> it's just a formula. I also know it doesn't do any logging, or "launch nukes", and that it is thread safe. So the type claims. Without looking at the implementation or using `-XSafeHaskell`, you don't know if there's an `unsafePerformIO` call lurking. /pedantry

Buttons840 10y ago
Even if the function had documentation that said "this function does not have side effects" it could still have side effects. So within the context of this thread, type signatures vs hand written documentation, I would say your point is a +0 for hand written documentation. Both type signatures and hand written documentation can lie.

14113 10y ago

I guess the counterexample would be library functions that look like: foo :: (BarMonad m, BazApplicative b) => ConfigurationStructure t -> (b -> m t) -> [b] -> t You can figure out a little of what it does, but how that fits into the application it supports, and what exactly it should be used for is non trivial. Haskell programmers (whose numbers I count myself amongst) saying that "the types are the documentation" is like expecting someone to build a lego model from the picture on the box, and saying "well the studs are the documentation of how the pieces fit together". It's correct, but it misses all the nuance of how the functions should be composed, not just how they can be composed.