7 ms·
Comments should be sentences
- h2s 13y agoNever write comments that re-state the implementation. # Try to read the configuration file. If this wasn't already obvious without the comment, then the code is a mess. Tidy the code up instead of painting over the problem with comments.
- aaronem 13y agoThat's a rule to be applied with a bit of nuance. Some things, especially in languages like Perl whose syntax already reads like a half-deliberate attempt to force an obscurantist style on the programmer, can't be made really obvious without doubling or tripling the length of the code in which they're implemented, something which imposes its own cost in readability and maintainability. In cases like that, it can be useful to add a few comment lines which briefly restate what the code implements, as both an aide-memoire for the original developer, and a minimal but immediately accessible answer to the question of "what the hell is this doing?" on the part of those who follow.
- robinh 13y agoI agree wholeheartedly. The syntax doesn't even have to be extremely obscure, it can be highly useful in lower-level languages such as C as well: Often, I just want to get a quick idea of what the next big block of code is going to do without having to read the entire block of code.
- dougk16 13y agoIn that case it's often (yea I know, not always) better to put that block in a separate function, like readConfigurationFile() instead of "// This block reads the configuration file.". I almost always treat the act of writing comments as a signal that my code is a mess...although they're sort of a necessary evil when you're down to crunch time.
- henrik_w 13y agoI agree, that's an excellent reason to create a function/method. Reason 7, self-documenting code: http://henrikwarne.com/2013/08/31/7-ways-more-methods-can-improve-your-program/ http://henrikwarne.com/2013/08/31/7-ways-more-methods-can-im... (but of course it doesn't mean that you never need comments)
- goblin89 13y agoI think it's said that you should document the "why" (as opposed to "what"), which is relevant when you're using an unconventional approach or for some other reason your code may not be understood immediately, or when business logic is involved.
- deleted 13y ago[deleted]
- deleted 13y ago[deleted]
- deleted 13y ago[deleted]
- deleted 13y ago[deleted]
- deleted 13y ago[deleted]
- robinh 13y agoA fair point, I should probably have mentioned that. Thanks for pointing that out.
- derefr 13y agoI 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?
- aaronem 13y ago> 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.)
- cema 13y agoI think another exception (in addition to the already mentioned help with an otherwise difficult syntax) is when comments are used to visually represent logical segments of the code. Some style guides suggest to write these in all caps. Eg: # CONFIG ... # LOCALS ... # EDGE CASES ... # REFORMAT INPUT ... # MAIN ALGORITHM ... Etc.
- h2s 13y agoRather than an exception, I think this is an example of the precise scenario in which it's most inappropriate to use comments. > visually represent logical segments of the code This is exactly the use case in which function definitions excel. Use functions for this, not comments.
- akkartik 13y agoYeah. A past HN discussion caused me to realize that comments are often used for two independent purposes: structure and commentary. Conflating the two has caused many conversations with the participants talking past each other. http://akkartik.name/post/2012-11-24-18-10-36-soc http://akkartik.name/post/2012-11-24-18-10-36-soc
- err4nt 13y agoMaybe this is because I come from an HTML + CSS background, but if I'm adding code to a file that may need to be moved around within that file or transplanted to another file I often use comments to mark the start and finish of Sachs ection or 'block' of code. It has little to do with how clean the code is, I can't imagine not having my way finding markers around!
- streetnigga 13y agoSuch commentary goes at the top of a function or class. You get more nuanced as you delve deeper into the textual abyss.
- Hansi 13y agoAgreed. I often try to make the point that when commenting people in my group should focus more on commenting on WHY and HOW rather than WHAT that is normally easily read from the code.
- deleted 13y ago[deleted]
- brudgers 13y agoLiterate comments are as a gateway drug to literate programming.
- cema 13y agoTrue. However, how useful literate programming is depends on a number of factors, time often being the main limiting factor.
- taeric 13y agoI've found tooling is the main limiting factor. Time certainly doesn't help, but seeing as how I couldn't use literate programming while my colleagues use their IDEs is ultimately what means I will be ditching it once I get help on things.
- brudgers 13y agoIf you're writing code that can be so easily understood that it does not require explanation, get a machine to do it.
- shizzy0 13y agoCue the self-documenting, we-don't-need-no-stinking-comments rabble rousers in 3, 2, 1... AND that's one reason why we're not an actual profession, people.
- vezzy-fnord 13y agoWe aren't?
- shizzy0 13y agoSee http://michaelochurch.wordpress.com/2012/11/18/programmers-dont-need-a-union-we-need-a-profession/ http://michaelochurch.wordpress.com/2012/11/18/programmers-d...
- vezzy-fnord 13y agoThat's adding some rather subjective baggage to the term "profession". I think the only thing really stopping software development from becoming a formal profession is a standardized code of ethics (of which there are several proposed) and a professional body to govern it (and let's face it, professional bodies can exert power to satisfy immoral agendas, much like unions). Then: Professionals are allowed and expected to dedicate about half their working time to career development and continuing education. Many software engineers will get fired if they get caught in that. This is pretty much false. Honestly, given all of this, I don't even think software development becoming a profession is desirable at all.
- shizzy0 13y agoSo, we aren't then, and we don't want to be. Yep, that's pretty much what I'm saying.
- diminoten 13y agoMy paycheck begs to differ! But really, comments are one way to mislead in code. If a comment is made that incorrectly states the intent of code, it's undeniable that this is harmful to the readability of the code.
- bjackman 13y agoI only started doing this recently. It occurred to me that I had some conception in my subconscious that natural language punctuation wasn't required in formal language code files. I think it may have simply been a cognitive spill-over from the fact that variable names start with lower-case characters. Looking back, it's totally ridiculous that I would, in a professional setting, put my name next to unpunctuated writing. Aside from being ugly and hard to read, it's straight-up unprofessional.
- anigbrowl 13y agoI like detailed comments myself, but this argument is hurt by taking them out of their context - it would have been more instructive to examine different styles of commenting to document a complex function or how they can help or hinder structural understanding.
- huhtenberg 13y agoComments should be meaningful. Whether they are sentences or a Morse code is secondary.
- cgrubb 13y agoAs of 2 months ago Ned doesn't follow his own advice: https://github.com/nedbat/byterun/blob/master/byterun/execfile.py https://github.com/nedbat/byterun/blob/master/byterun/execfi...
- akkartik 13y agoWhat're you referring to? They all seem to be complete sentences with capitals and full-stops.
- cgrubb 13y agoSorry, I didn't think it was hard to find these: 13 open_source = tokenize.open # pylint: disable=E1101 27 # from coverage.py: 30 # In Py 2.x, the builtins were in __builtin__ 33 # In Py 3.x, they're in builtins 38 """The same as s.rsplit(sep, 1), but works in 2.3""" 101 # Create a module to serve as __main__ 140 # Restore the old __main__ 143 # Restore the old argv and path A reminder of what the blog post tells us: Start comments with a capital, have a subject and a verb, and end them with a period.
- shoo 13y agohttp://en.wikipedia.org/wiki/Tu_quoque http://en.wikipedia.org/wiki/Tu_quoque
- cgrubb 13y agohttp://en.wikipedia.org/wiki/Straw_man http://en.wikipedia.org/wiki/Straw_man
- sefk 13y agoI love the attention to detail Ned.
- deleted 13y ago[deleted]
- akkartik 13y agoContrast PG's style, which had a deep influence on me: https://github.com/arclanguage/anarki/blob/master/arc.arc https://github.com/arclanguage/anarki/blob/master/arc.arc. There's something to be said for an aesthetic of conciseness that lets one spend less time scrolling around and more time just thinking about what's in one's field of view. That includes stripping comments of unnecessary verbiage. The article does make one good point: that when you add to a terse comment you often have to add capitals and punctuation. But that is also often a signal to me to ask why I need to switch from communicating a fact to creating a narrative. Is the narrative really necessary? Often I find some way to reorganize the code without needing to narrate it. Relevant is http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.htm.... (But I'm not claiming everybody who uses complete sentences is a noob.)
- ams6110 13y agoA developer I used to know put it thus: "A comment is an apology." I never asked him to explain that, but I guess he meant it's an apology that the code itself is not self-explanatory. Clear, even verbose commentary can be helpful. But where it often breaks down is when the code is revisited, and the comments are not updated as well. So my practice now is to use comments in early development to help me remember what I was thinking in that bit of code, but then remove most of them during clean-up and refactoring unless something particularly non-obvious is going on. It makes future maintenance of the code less likely to diverge from the (usually unmaintained) comments. Good code review could help here: "Hey, the diff shows you changed six lines of code in that function but the comments are the same, do they need to be revised?" But I've never worked anywhere where EVERY commit was reviewed, rather a sampling is selected for weekly review. that leaves a lot of opportunity for things to get missed. Bottom line: extensive comments can add to workload when fixing bugs or making enhancements. So only use them when they really count.
- taeric 13y agoMeh, I'm a huge fan of "readable code" that is easy to follow and just makes sense with no need for explanations. And then there is code that is non trivial. Too often I've found that vast amounts of effort were put into keeping something "readable" to the point that all of the extra readable hints either just got too large and unwieldy, or it prevented the developer from picking an easy and straight forward solution. (And to be fair, often that developer was me.) I think there is a very real divide between what the logical flow for a computer to be presented something and the narrative flow for explaining that to another developer are. And no amount of clever variable/function names will really help here. In fact, often times it can be worse. The proverbial isle of a grocery store. Too much to look at with no obvious "main" method. There is a reason it is a "rookie mistake" to have giant methods that do too much. When it comes down to it many people were only trying to get their program to do one thing. Cluttering their memory with the myriad steps necessary to get there is a large hurdle to get back into something.
- tsiki 13y agoThe programmer who doesn't change the documentation when changing the code is usually the same one who doesn't change the function name when changing its functionality. If a bad programmer is tweaking your code, it doesn't really matter if the documentation is in the variable names or in the comments.
- grantph 13y agoI usually start by writing comments first in plain English based on a variation of psuedocode. That way I'm focused on process first without distraction. Comments are the plan. Clearly articulated steps like any good cookbook. Easy to translate into any language. // 1. Write plain English psuedocode. // 2. Translate into scary looking code blocks. // 3. If maintaining, remember to update comments first (goto Step 1, then Step 2). The irony is another developer once claimed that my code was generated by a machine. Apparently it was too methodical to be human. Like that was some excuse for him to write crappy code. Urgh! To be great at anything, you need to have excellent communication skills!