• 0 Posts
  • 4 Comments
Joined 17 days ago
cake
Cake day: June 28th, 2024

help-circle
  • And isn’t it such a dangerous overlap! The coder whose writing (in their native language) is unclear, repetitive, convoluted, or hard to follow too often produces code with the same qualities. It’s even worse when the same coder believes “code is self-documenting” without considering why. Code self-documents with careful and deliberate effort, and in my experience, it is the really good writers who are most capable of expressing code in this way.




  • I actually agree that “good enough” code can be self-documenting, but it isn’t always enough to achieve my goal which is to make the code understandable to my audience with minimal effort. With that goal in mind, I write my code as I would write a technical document. Consider the audience, linear prose, logical order, carefully selected words, things like that… In general, I treat comments as a sort of footnote, to provide additional context where helpful.

    There are limits to self-documenting code, and interfaces are a good example. With interfaces, I use comments liberally because so many of the important details about the implementation are not obvious from the code: exactly how the implementation should behave, expected inputs and outputs under different scenarios, assumptions, semantic meaning, etc. Without this information, an implementation cannot be tested or verified.