DEV Community

Discussion on: "Do not comment on your code, it should be self-documented". Well... I don't agree.

Collapse
 
jankapunkt profile image
Jan Küster

Good variable names indicate what concepts are involved. Clean code can document the execution model (what the code is and how it functions) but code itself can not explain "why" a certain routine had been chosen in favour of others.

From an engineering perspective the "why" is important to reason about the code on a higher level than just the few lines in front of the eyes.

From my experience with reading many many open source project code I can only say: the more comments explain what's going on, including well written jsDoc, the better it was to create a PR to that code.