DEV Community

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

Collapse
 
moianwatkins profile image
Ian Watkins

I do both. Saved me many more times I care to remember.

Sure, name functions and variables in a meaningful way but put a comment block at the top of the function to explain the what, why and how.

Taken further, try this method (it's what I do and often commented upon in a welcomed way):

  1. Name your function and input variables in a useful way.
  2. Now write individual comments explaining the process.
  3. Now write the actual code under each comment.
  4. Review whether the line of code is easily understandable on it's own. If so, remove the comment.
  5. Function all good and understandable to anyone? You're done. If not, put in a comment block at the top of the function explaining the why and how.

Like tests, comments are best written before the actual code but they must be reviewed after the code is written to ensure their value.