Hacker News new | ask | show | jobs
by kbenson 4234 days ago
I find that statement to generally sound good, but there are lots of nasty details that are often overlooked. Taken to it's extreme, it leads to overly commented code that tries to explain to non-programmers what a program is doing. I find my time better spent than doing that for all code I write. Then there's the question of who the expected reader is? Some future version of you? Some coworker or successor in the same field, expected to be at relatively the same level in the relevant areas? Some beginner in those some fields. A programmer without experience in the relevant areas, or not yet comfortable in the chosen language and able to understand it's idiomatic usage?

Don't get me wrong, I'm in favor of the concept, I just find that most people seem to put very little thought into what it means in practice.
2 comments
Moru 4234 days ago
I always learn better if I write things down. I also remember better if I wrote down what my code does as detailed as possible. Also improves the search-possibilities when I need to find something three years later :-)
link
warcode 4234 days ago
"Others will have to read your code"

Comments are not "code". Your code should, when written impossibly well, explain itself through variables, function names and composition. Better code equals less comments needed.

link
kbenson 4234 days ago
I think this is exactly the sort of position that leads to problems later when people find their implicit assumptions don't match with those of others.

I can write perfectly idiomatic code in Perl, using map, grep, simple postconditionals, taking advantage of built in functions that topicalize, knowledge of when items are passed by reference or copy (or a sort of alias), and the code will be very succinct and readable to Perl programmers. Should I forego some of that to make the code more readable to general programmers? Doing so will necessarily make the code slightly less readable to those expecting idiomatic Perl.

I'm not espousing one way over the other, just that it should be thought about with regard to the purpose of the code, who owns it, and who will be looking at it in the future. The exact answer may differ in different situations.

link