Don’t document your code. Code your documentation.

Dani Morillas on January 25, 2017

This is one of the great discussions among developers: document or not document your code? Is it worth writing documentati... [Read Full]
This is a single comment and its replies view full discussion

This is forgetting the (few) times you have to document why you are doing something non-obvious. I otherwise agree documenting the "what" is generally useless and redundant and quickly become stale and error-prone. I however also agree with other commenters that it can be much easier, and not less readable, possibly more, to sometimes add a one line comment rather than extracting a piece of code into its own function/method.

Documenting the why, rather than the what, can be absolutely crucial. As for comments being easier to understand than code being extracted into separate functions; I'd say there is far more chance of a comment being out of date than a function name (although the latter is also entirely a possibility).

code of conduct - report abuse