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).
The pendulum swings. In college, I was taught to comment everything because "that's what industry will expect." Getting into industry was quite a shock, needless to say.
I heartily agree your code should be readable, and "say what it does."
Sometimes, it needs to do something....odd. The WHY for that should be a comment.
External documentation has its place, particularly for how to get someone else set-up on developing the module, and code examples for idioms.
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.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
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).
Amen.
The pendulum swings. In college, I was taught to comment everything because "that's what industry will expect." Getting into industry was quite a shock, needless to say.
I heartily agree your code should be readable, and "say what it does."
Sometimes, it needs to do something....odd. The WHY for that should be a comment.
External documentation has its place, particularly for how to get someone else set-up on developing the module, and code examples for idioms.
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.