Hacker News Reader

Comment by ralphos | Hacker News Reader

If I wrote an article with the same title I would only include one thing to remember when coding and that is to write code with the expectation that others will have to read your code. (This of course assumes you're not an ass who wants to make people's lives more difficult!)

View on HN

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.

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 :-)

"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.

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.

If you return to your code a couple weeks or months later, chances are you'll be in the 'others' category too. So by writing readable code, you're doing yourself a favor most of all.

And THIS is how all the someones that "will always tell you you’re doing it wrong" always start...

(but I'm not saying that it's not an important point)

Reply on news.ycombinator.com