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).
I was about to write exactly the same post :)
The only thing is that it's extremely complex to teach that to youngsters. Code reviewing doc from juniors takes a lot of trips back and forth in the comments.
I guess that clear a clear doc comes with a clear vision of what you're doing.
We’re a place for programmers to stay up-to-date, learn new skills, and share ideas.
We’ll never post without your permission.