Δαφνη Ευτυχια Αρθουρος

"Perhaps that's the dirty little secret of code comments: to write good comments you have to be a good writer. Comments aren't code meant for the compiler, they're words meant to communicate ideas to other human beings. While I do (mostly) love my fellow programmers, I can't say that effective communication with other human beings is exactly our strong suit. I've seen three-paragraph emails from developers on my teams that practically melted my brain. These are the people we're trusting to write clear, understandable comments in our code? I think maybe some of us might be better off sticking to our strengths -- that is, writing for the compiler, in as clear a way as we possibly can, and reaching for the comments only as a method of last resort." -- Jeff Atwood, 2008-07-24 [emphasis in original]

[I remain a lots-of-comments fan, but this essay is making me think about that again, and consider whether my attitude may be biased by my own ability to write. And my wilingness to edit the darn comments when I edit the code. But I tend to use more comments than I used to, and perhaps that's partly automatically attempting to compensate for what fibromyalgia has stolen from me in terms of short term memory and ability to keep a lot of "state" in my head at once. I probably need comments more now. But when maintaining systems bult by others, I always wanted enough "how this is organized and what it's gonna do" comments in the code to get a head start on knowing where to look for the bit I needed to fix or modify. ("There should be a separate design document," you say? Most projects I was called in to update (a) never had an overall design-of-the-project document, (b) had lost that document, or (c) had one written so that it made no sense unless you already knew everything it was supposed to tell you.)]