1. 4

    I find that when I write code, I typically comment the “what” as a last resort.

    When writing BASH, there’s far too many archaic invocations that are difficult to pop into a search engine. I almost always document the “what” in those situations, because I want to save the next engineer time when they pop in to make a modification or fix a bug.

    I generally see documenting the “what” as necessary but not ideal. Kind of like technical debt. If I need to explain what is happening, I probably didn’t structure the code well enough to communicate what is being done.

    That all said, I feel like documenting the why not the what is like any practice. It’s a good “rule” to consider, and break when it makes sense.

    1. 2

      This is my favorite dungeon map maker yet! The interface feels so fluid and flexible.