Comment on How to properly document code?

zarlin@lemmy.world ⁨10⁩ ⁨months⁩ ago

• Carighan@lemmy.world ⁨10⁩ ⁨months⁩ ago

  Yeah, my general rule of thumb is that the following 4 things should be in the documentation:

  • Why?
  • Why not?, which IMO is often more important as you might know a few pitfalls of things people might want to try but that aren’t being done for good reasons.
  • Quirks and necessities of parameters and return values, this ensures that someone doesn’t need to skim your code just to use it.
  • If applicable, context for the code’s existance, this is often helpful years down the line when trying to refactor something.

  source

  • MagicShel@programming.dev ⁨10⁩ ⁨months⁩ ago

    Yep. I mostly document why the obvious or best practice solution is wrong. And the answer is usually because of reliance on other poorly written code - third party or internal.

    source