4 ms·

That doc link is funny, but it's also very frustrating -- you would think that after all those warnings, there would also be some glimmer of information about w

That doc link is funny, but it's also very frustrating -- you would think that after all those warnings, there would also be some glimmer of information about what sets the accursedUnutterablePerformIO function apart from unsafePerformIO, or at least why it exists, but apparently not. It's clearly important because most of the core functions in Data.ByteString call it. It seems like the authors have decided that the trickiest, most magical parts of their codebase are exactly where they don't care about useful documentation. That seems like a bizarre strategy unless they plan to never let anyone else help with maintenance.

derefr 4y ago
“If you aren’t willing to read the source of the function to learn what it does, we don’t want you anywhere near it. No summary short of the function itself can accurately communicate how much of a fragile hairball of edge-cases this function is, and how many things you have to know about to correctly call it.”
- bradrn 4y ago
  This is pretty much correct. For reference, here’s the original documentation (changed in commit 80ff4a3018cd8909abb1d4e0c32f012a523883ec): -- | Just like unsafePerformIO, but we inline it. Big performance gains as -- it exposes lots of things to further inlining. /Very unsafe/. In -- particular, you should do no memory allocation inside an -- 'inlinePerformIO' block. On Hugs this is just @unsafePerformIO@. The commit message notes that ‘We've had a few instances of people being tempted to use it without really understanding the consequences’.
  - throw-ru-938 4y ago
    I wonder why inlining the function makes it that much unsafe.
- Dylan16807 4y ago
  Good documentation tells you a lot more than the source could. Especially when you're talking about horrific side-effects.
- kstenerud 4y ago
  This is the worst kind of arrogance. All you're doing is reducing the number of people who'll understand what's actually going on, which not only makes it less likely to be used properly; it also makes debugging code that uses it more difficult. You're deciding for other people what they should and should not know. Another word for this is gatekeeping. Don't do that. You're not the other person. You can't read their minds, nor can you fathom their reasons. Deliberately hamstringing folks is bad policy, and supremely arrogant. Just document it properly, lay out the risks, and leave it to the reader to decide on policy.
  - fxtentacle 4y ago
    Oh wow your comment really rubs me the wrong way... In my opinion, it is properly documented, almost perfectly so, by the authors giving you the full source code. If you are not willing to read the source code, but instead always blindly rely on documentation to be correct, then in my book that's just lazyness.
    - MrGilbert 4y ago
      I'd argue that both of you are somehow correct. Give me the code, so I can see what it does. And give me documentation (be it correct comments, a dedicated documentation or whatever) to know why it does something. Code states the obvious, but you cannot read between the lines.
      - mkmk3 4y ago
        It reminds me of how narrow roads are sometimes used to slow traffic, though I dont know if its effective here. Im hesitant to discourage it when the language is so explicit about it being bad, it might be quite effective afaict
    - kstenerud 4y ago
      Documentation is not a substitute for reading the code, but rather a complement to it. Code by itself is a limited medium that can only do so much. Asking someone to rely solely on code to explain a complicated subject is counterproductive (the more complicated the code is, the harder it is to guess whether something in the code is a mistake, or working as intended with some unknown reasoning behind it). Documentation points out the non-obvious parts, the reasoning behind it, the subtleties, the gotchas (things to watch out for), the best practices, etc. Documentation is a map to guide the user, not an end-all-be-all about what the code does. When the code does non-obvious things or has non-obvious reasons, you need both code and documentation.

derefr 4y ago

“If you aren’t willing to read the source of the function to learn what it does, we don’t want you anywhere near it. No summary short of the function itself can accurately communicate how much of a fragile hairball of edge-cases this function is, and how many things you have to know about to correctly call it.”

bradrn 4y ago
This is pretty much correct. For reference, here’s the original documentation (changed in commit 80ff4a3018cd8909abb1d4e0c32f012a523883ec): -- | Just like unsafePerformIO, but we inline it. Big performance gains as -- it exposes lots of things to further inlining. /Very unsafe/. In -- particular, you should do no memory allocation inside an -- 'inlinePerformIO' block. On Hugs this is just @unsafePerformIO@. The commit message notes that ‘We've had a few instances of people being tempted to use it without really understanding the consequences’.
- throw-ru-938 4y ago
  I wonder why inlining the function makes it that much unsafe.
Dylan16807 4y ago
Good documentation tells you a lot more than the source could. Especially when you're talking about horrific side-effects.
kstenerud 4y ago
This is the worst kind of arrogance. All you're doing is reducing the number of people who'll understand what's actually going on, which not only makes it less likely to be used properly; it also makes debugging code that uses it more difficult. You're deciding for other people what they should and should not know. Another word for this is gatekeeping. Don't do that. You're not the other person. You can't read their minds, nor can you fathom their reasons. Deliberately hamstringing folks is bad policy, and supremely arrogant. Just document it properly, lay out the risks, and leave it to the reader to decide on policy.
- fxtentacle 4y ago
  Oh wow your comment really rubs me the wrong way... In my opinion, it is properly documented, almost perfectly so, by the authors giving you the full source code. If you are not willing to read the source code, but instead always blindly rely on documentation to be correct, then in my book that's just lazyness.
  - MrGilbert 4y ago
    I'd argue that both of you are somehow correct. Give me the code, so I can see what it does. And give me documentation (be it correct comments, a dedicated documentation or whatever) to know why it does something. Code states the obvious, but you cannot read between the lines.
    - mkmk3 4y ago
      It reminds me of how narrow roads are sometimes used to slow traffic, though I dont know if its effective here. Im hesitant to discourage it when the language is so explicit about it being bad, it might be quite effective afaict
  - kstenerud 4y ago
    Documentation is not a substitute for reading the code, but rather a complement to it. Code by itself is a limited medium that can only do so much. Asking someone to rely solely on code to explain a complicated subject is counterproductive (the more complicated the code is, the harder it is to guess whether something in the code is a mistake, or working as intended with some unknown reasoning behind it). Documentation points out the non-obvious parts, the reasoning behind it, the subtleties, the gotchas (things to watch out for), the best practices, etc. Documentation is a map to guide the user, not an end-all-be-all about what the code does. When the code does non-obvious things or has non-obvious reasons, you need both code and documentation.