DEV Community

Discussion on: Self Documenting code isn't

Collapse
mnivoliez profile image
mnivoliez

I totally agree with what you said. From my point of the view (and it may not be the good one) semantic is the key to everything. We write code for others, if we did for machines it should more look like assembly. The problem I got with comments is that often they are missused (at least in France, thanks to schools which ask to write comments everywhere even for saying it's an int). Most of the time, the code can express itself.
This is what I avoid:

// this function makes coffee
fn something() {
...}

This is what I strive for:

fn make_coffee() {
  ...
}

Same goes for parameters. In few words, don't do with comment what you can do with code. Instead use comment for what code cannot provide. For exemple the why as you said, but also exemple of the use, to explicit the chain of mind comming to this point. For exemple, some tools like rust documentation generator propose even the test as doc, test embedded in comment.

In short, too much comments kill the purpose of it. Like everything, it's a tool that should be use with care.

That's only my opinion and I may be wrong here.