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

I would think that a comment re-summarizing the function in natural language would also "double or triple the length of the code." Wouldn't it be better, then, to just let the code itself expand, rather than expecting maintenance programmers to both read your comments, and then use them to parse an otherwise-inscrutable construction?


> I would think that a comment re-summarizing the function in natural language would also "double or triple the length of the code."

It needn't; the example I had in mind when I wrote my earlier comment was some Perl code I wrote on Friday to automate the task of taking one database, full of relations dependent on auto-increment column values, and merge its contents into another database of identical schema but conflicting auto-increment values, while maintaining the relationships between rows. This worked out to ca. 60 lines of Perl, and unusually dense and hard-to-read lines even for that language; to this, I added about a half-dozen terse but informative comment lines to serve as guideposts for my primarily Python-hacking colleague and co-conspirator on this project.

A 10:1 code-to-comments ratio is unusually high, granted, and perhaps I could've instead written the code to use a lot more temporary variables and otherwise ballooned it out to twice or three times its length, but I don't see how that would've aided readability; on the one hand, there'd be a lot more state to keep track of, and on the other, it'd no longer fit on a single screen, and would thus require the reader to scroll hither and yon while trying to make sense of it.

Some things are inherently not simple, and I'd argue that complex manipulations of complex data structures fall well within that category -- in such cases, there's only so far you can simplify the algorithm before it ceases to work as you intend. When you write such code, you more or less have to rely on the native competence of whoever else has to work with it, because there's only so much hand-holding you can accomplish either in comments or in code.

Fortunately, in this case I can safely so rely; my colleague is at least as capable as I am, so the comments I added are the same sort I'd appreciate having when attempting to digest a complex algorithm in a language not wholly familiar to me -- for example, if he'd written this code in Python, rather than me writing it in Perl.

(Of course, the real problem is that, while both languages make it possible to perform the sort of manipulation necessary here, neither language is really well suited to it; if my colleague knew Lisp as well as I do, I could've written the bloody thing in fifteen elegant and highly readable lines, and we both could go on with our lives. But I've more or less given up hope of introducing Lisp at my place of work; even the most seasoned programmers among my colleagues, when exposed to parentheses, turn pale green and make excuses to be somewhere else in a hurry.)




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

Search: