Post #2050531
2026-02-03 15:24 UTC
@mahryekuh Ooh, I'm sorry to hear that! I always say comments are for the "why". My biggest troubles are from a junior who doggedly follows clean code principles even when it makes no sense. I don't refactor or change his code for the sake of it if it works, but often it's far harder to grok and work with.
Replies (1)
-
@mahryekuh@hachyderm.io 2026-02-03 17:55
@Lacey Thank you for the compassion! I am with you on the “why”. Code should be self-describing, so the docstrings are there to: 1. Summarize the contents (reduces cognitive load). 2. Explains intentions, caveats, and philosophy, if needed. 3. Optionally shows implementation examples (although I’m personally not a fan). Clean code is such a weird concept. Code can be too clean, which means it’s without context. It’s like a house that is staged for sale, or a hotel room: it has the necessities to survive, but you wouldn’t live there.