Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

While I agree that sometimes I do break my rules myself, when I don't want to spend 15 minutes to name something, I don't think your example convinced me of your case.

Would you honestly expect someone to know by heart what "sort -rn" or "uniq -c" do? This forces the reader to know what all the arguments mean by anyone reading this code.

If you'd try to push this code, I wouldn't let it pass code review without a comment on each line (except plain "sort", that one's really obvious).



> Would you honestly expect someone to know by heart what "sort -rn" or "uniq -c" do?

For people that program regularly in bash, I would. If it was a rare bash script in a code base where many team members didn't know bash well, comments would be appropriate. Even there, though, that's not the same as introducing superfluous intermediate variables.

The larger point here relates to "intended audience" or "what competencies may I assume the reader has?". This is a matter of art, not science, and highly context dependent.

Take an extreme version of the point you just made:

    const x 4*2;
"Would you honestly expect someone to know by heart that `*` in JS means multiplication?"

Clearly that is absurd, because that knowledge is an assumed competency.

What about `**` for power?

What about `^` for XOR?

What about knowing that `-~x` is equivalent to `x+1`?

Where exactly do you draw the line? You can "err on the side of over-commenting" but only so much, because taken to an extreme it hurts readability, and will annoy everyone.

Responsibilities are distributed. Is clarification the responsibility of the author or the reader? What can I assume "a reasonable reader" should know? The answer depends on many things. But the right answer isn't a blanket policy of assuming incompetence and explaining every detail with comments or intermediate variables.


I think we're in agreement on the framework of the debate (rare), it's just that from personal preference we draw different lines on what information is reasonable to assume your reader has.

I personally have not regretted much assuming incompetence in my future self on small things, but it's your choice to what standard you hold yourself against.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: