Comments and explanations - how to do it better?

My philosophy is this: Forget about that code will be executed by a computer. You write code so it to be read by another human being. Writing code is social communication first of all.

Too much comments, especially about obvious things is not good. A person could easily understand what code does, comments should answer to why. Express your motivation or rationale why are you doing this or that.

Writing code is social communication first of all.

That is the best explanation I have read yet.

"Writing code is social communication first of all."

That is brilliant - thank you.

Paul

Writing code is social communication first of all.

That is the best explanation I have read yet.

"Writing code is social communication first of all."

That is brilliant - thank you.

Paul

That's a huge stretch, but the general idea is true indeed - if it was only intended to be read by a machine, it would be binary and not human-readable.