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

Well, I think modern coders have confused the reason we should be documenting and commenting. My policy is pretty simple:

  • You should always be able to tell WHAT the code is and does by how you write it (your point.)

  • The WHY (the intent of the code) is rarely something one can figure out in the best of circumstances. This is where commenting comes in - but comment WHY, not WHAT.

  • Documentation, in the literal sense, should be hand-written for your end users. HOW do you use the library/application? I hate it when projects call API docs "documentation," and don't bother with anything else, as it is nigh impossible to learn to use an unfamiliar library from the API docs.

In short, we MUST do all three: code your documentation (WHAT), comment your code (WHY), and document your project (HOW).

code of conduct - report abuse