DEV Community

Discussion on: Don't document your code. Code your documentation.

Collapse
 
tbroyer profile image
Thomas Broyer

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.

Collapse
 
nimmo profile image
Nimmo

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).