11 ms·

Useful and useless code comments

126 points by jerodsanto 5y ago

dmckeon 5y ago
How, why, which, where, when, what, who. The code says how. The commit says what, and where the edited lines were/are in which files, when the edits were committed, and who committed them. The comments should say why, iff a why is needed.
tshaddox 5y ago
I sometimes use comments that are nearly as “obvious” as the examples, but more as a human-readable outline of the code block. The point isn’t to provide additional clarity after someone reads the code, but rather to be the first thing someone (especially myself, later) reads when encountering that code block.
gregschlom 5y ago
Fully agree with the author here. I write comments that "repeat the code" all the time, and I like to read them in other people's code. It allows the reader to quickly skim through large portions of code without having to fully decode each line. Obviously, I'm not talking about comment like this (which I see all the time): // adds 1 to x x += 1; That is certainly useless, even annoying. But a small comment every 2-3 lines to explain the following 2 to 3 lines is generally very useful.
- themodelplumber 5y ago
  It's funny to recall that when I was about 11 years old, 30+ years ago, I would have thanked you profusely for that comment, instantly unraveling the += mystery.
  - dmurray 5y ago
    But in hindsight, it wouldn't be a good comment, because that information is misplaced. The perfect time for you to encounter that comment is the first time you ever encounter the += operator, not every time you encounter it. I generally think you shouldn't comment to explain your use of a language feature, even an unusual one. The exception: when there exists an idiomatic alternative which you intentionally didn't use, then a comment can explain why.
    - IlliOnato 5y ago
      ... or when the feature is counter-intuitive and actively confusing, like "oct" and "hex" operators in Perl that do opposite of what one not familiar with them would guess. Even after many years of programming in Perl I found comments like # FROM hex, not TO hex! useful.
whoisjuan 5y ago
I’m on the same page. Just look at the given example. Does it look wasteful to say that you’re adding a vertical bar when you have the following line of code?: // Add a vertical scroll bar vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); Perhaps. But the comment is making a lot more than simply describing what’s below of it. The comment is doing the following things: - It’s creating a visual boundary that aids to the readability of the code. It adds context within a large set of instructions. - It’s providing context that might not be there for the person who is reading the code. Just because you think the name of that function and what you’re passing into it clearly describes the instruction, doesn’t mean that everyone else does. At least not in a snap. The comment helps to reduce the cognitive load of reading the code because it’s explaining the instruction in plain english. - The comment itself could be part of a larger narrative that is trying to explain what that file is doing. It’s not there to make the obvious more obvious. It’s there to make the whole file obvious which is evidently important to write readable code. Look. I know there are purists that get offended with obvious code comments. But you cannot expect everyone to have the same proficiency you do. Writing good code, also means writing code that a newbie can at least comprehend. And sometimes that means explaining in plain english what could be already obvious to you. People like to think they are writing code like prose that is delightful to the reader, but many times are just writing reader hostile code. Write code focusing on clarity. Not elegance by obscurity. Make it clear, add structure, add visual boundaries. Ask yourself if what you think is obvious is obvious to everyone. If in doubt explain it with a comment. I’ll rather see an obvious comment and say “well that’s obvious” than spending valuable time trying to understand what certain piece of code is doing.
- nitrogen 5y ago
  Make it clear, add structure, add visual boundaries. And push back hard against linter/prettifier rules that remove all developer discretion from layout and structure.
  - wilsonrocks 5y ago
    I'm all in on prettifying... If it's done automatically. I find it such a good tradeoff to not have to think about it that I'm happy to accept the times when I think my discretion would do it better. That said, I've started to develop strong views on some eslint rules. Usually around things being errors that should be warnings in development, like logging messages or debugger or unused variables. I like to run in CI with max warnings being zero to catch them then.
hcarvalhoalves 5y ago
IMO, if I feel the need to add comments to explain code blocks like this: > // Add a horizontal scroll bar > hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); > add(hScrollBar, BorderLayout.SOUTH); It's a sign I should be writing code that reads more like: > addHorizontalScrollBar()
- cdubzzz 5y ago
  Do you then document the new function, though?
  - pixel_tracing 5y ago
    I think the function name is pretty self documenting, I would go a step further and make a function named addScrollBars() clear on its intention here
    - cdubzzz 5y ago
      Sure. Agreed. But I still docblock every function I write so this wouldn’t change much with respect to usefulness of the documentation.
  - lkrubner 5y ago
    You've heard the XTreme slogan "Where you would write a comment, we would write a method"?
- nitrogen 5y ago
  If you're building a UI frame, like in this Swing example, I think it's reasonable to keep the code in a single method and separate it into functional blocks with comments. But the variable names and comments should still include a bit more of the why. Example: // Build the data table view ... // Add horizontal scroll bar to the data table view // This is needed if the table has more than N columns tableHScroll = // etc // Build the data navigation sidebar ... As an aside, I wish web UI programming was more like a declarative form of Swing (that is, a widget- and layout-oriented tree), rather than the current mess of React and a text-/document-oriented tree.
hvocode 5y ago
I write comments based on what I expect I will need to know if I close the editor and don’t look at the code again for a couple years and will need to jump back into it as quickly as possible. That usually means I don’t want to waste the time of future me reconstructing what the code denotes if I could just write it down in a comment in he first place.
jaggederest 5y ago
This is also somewhat about language choice. Languages more oriented towards natural language need less commenting. If I were writing C++ or assembler on a regular basis, I would probably be writing a lot of "what" comments. My favorite comments are actually "what" comments, but that clarify something opaque about the code, e.g. const R = 6371e3; const φ1 = lat1 * Math.PI/180; const φ2 = lat2 * Math.PI/180; const Δφ = (lat2-lat1) * Math.PI/180; const Δλ = (lon2-lon1) * Math.PI/180; const a = Math.sin(Δφ/2) * Math.sin(Δφ/2) + Math.cos(φ1) * Math.cos(φ2) * Math.sin(Δλ/2) * Math.sin(Δλ/2); const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a)); const d = R * c; It's extremely difficult to analyze that and say oh, obviously, that's the haversine distance formula, and the result is the distance in meters, of course. It would be slightly easier in a language with type annotations, but not a bunch easier. You add a simple // haversine distance formula, result is d in meters and now you can google the wikipedia page to understand the context and history.
- BrissyCoder 5y ago
  Modern C++ is actually quite readable now imo - fairly close to C#. Has come a long way in the last 20 years. That being said most code out there is legacy of course...
  - jaggederest 5y ago
    Yes, I'm probably just traumatized from trying to look at 3d engine code "back in the day" :)
- tharkun__ 5y ago
  I imagine you will use this in more than one place in the code. Why does it need a comment? Naming the function should be enough for most of it. Other languages probably aren't better at specifying the "in meters" part either, are they?
  - panopticon 5y ago
    A function still seems appropriate even if you're not using this multiple times. Unless how you're computing the haversine distance is relevant to the surrounding code, it would be much more readable to extract it out.
bdcravens 5y ago
I generally save comments for WTF code, or to put links that document what's going on. I try to abstract things as a lot of folks are mentioning here, but that just pushes things to another place. Eventually someone is going to need to debug that code. Here's a Puppeteer example, where text is being split into nodes to extract based on line breaks: /* https://medium.com/@roxeteer/javascript-one-liner-to-get-elements-text-content-without-its-child-nodes-8e59269d1e71 */ return await this.page.$eval(selector, e => { const s = [].reduce.call(e.childNodes, function(a, b) { return a + (b.nodeType === 3 ? b.textContent : ''); }, ''); return s.replace(/\s+/g,' ').trim(); });
- ninthcat 5y ago
  If you rewrite it so it's no longer a cryptic one-liner, it's probably easier to understand this way without a comment than the other way with one. return this.page.$eval(selector, (node) => Array .from(node.childNodes) .filter((child) => child.nodeType == Node.TEXT_NODE) .map((child) => child.nodeValue) .join('') .replace(/\s+/g, ' ') .trim() );
  - dmurray 5y ago
    Hope this refactor was well unit tested, because it looks to do something a lot different from the original code.
mumblemumble 5y ago
The more I see people opine on commenting style, the more I want to just spam the "you do you" button and get on with my life. I have a way that I like to do it. Other people on my team have their own ways. My way is not hurting them. Their way is not hurting me. Either of us trying to impose our way on the other would hurt both of us.
- deleted 5y ago
  [deleted]
thirdplace_ 5y ago
This text reminds me of the fact that value judgements are personal and subjective. So, one man's benefit is another man's cost. To make matters worse, it's hard to do math with these things, thus net benefit can't possibly be calculated.
BurningFrog 5y ago
The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it. The never, ever happens consistently. So soon you have the "man with two watches" problem. The code says one thing, and the comments say another. You could fix it, and sometimes you spend that time, but inevitably you also stop reading the comments, since they're not reliable. I've never seen this not happen in comment heavy projects.
- whoisjuan 5y ago
  This is something you can quickly see with Git. If the comment lines are older than the code lines you can at least start with the assumption that the comment might be outdated. That’s more useful than dealing with stale documentation which can also be outdated. At least with code comments you have contextual proximity.
  - tylorr 5y ago
    This sounds like a great idea for an editor plugin.
    - vSanjo 5y ago
      1. Iterate through all blocks of comments. 2. Determine if there have been updates within the block of comments first (one line of three updating, for example). 2. For each block of comments, find the proceeding block of code. 3. Compare the last update of comments to the last updates of the code. 4. Warn the user when it's over a threshold. Something like that?
- l8again 5y ago
  While that is true, it isn't a problem inherently with comments.
- tablespoon 5y ago
  > The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it. > So soon you have the "man with two watches" problem. The code says one thing, and the comments say another. You could fix it, and sometimes you spend that time, but inevitably you also stop reading the comments, since they're not reliable. When you think about it, function and variable names are comments. Should we not use those because they need to be maintained with the code?
l8again 5y ago
I always wondered if the "useless comment" comment was really a way of bragging employed by experienced programmers (or their wannabes). Why is it a burden on anyone? Most IDE clearly highlight the comments so you can tune it out. Also, even if it is obvious, at least when a bug presents itself, you don't have to spend much time figuring out the intention of the author and if it is indeed a bug or by design.
habeebtc 5y ago
Article mentions my preferred take: stating my intention to help keep me honest on what I am trying to achieve. Also: they function like an anchor tag. If you are spelunking a new code base for a specific functional area, a search in plain English would let you jump to the right spot more quickly.
dec0dedab0de 5y ago
My favorite comments are long winded apologies to my future self, or whoever has to work with the ugly hack I'm putting together to meet a deadline.
almostdeadguy 5y ago
For the most part I take no issue w/ the style of comments that act as a statement of intent. It only becomes a problem when comments are used to paper over the author's own indifference to making the code itself legible, and that's where I expect critiques like this truly come from. Comments without legible code do not help, as the comments are not a proof of correctness or verification that the author's intent has been carried out. You still need to read the code to understand the program. Code legibility is not unlike legibility in written language. Short sentences and paragraphs, clear transitions, well-defined hierarchy, consistent structure. Say more with less. Comments are often like footnotes: they elaborate upon the author's intent, provide a mental palette cleanser, elaborate on a digression in a way that limits distraction, or occasionally break the fourth wall. Comments are improper when they try to serve other means. For instance comments about invalid uses of a function/class/etc. when the type system can be used to prevent illegal usages of code. Or when comments are used to explain what is happening in extremely branchy, anti-modular, or otherwise illegible code.
Someone1234 5y ago
When I was doing CS in college, bad commenting was an academic requirement: As in your grade would be worse if you commented appropriately. Over multiple courses including software engineering, comment quality and or correct use of comments was never in the syllabus. But in several courses they wanted to see the code heavily commented, to the point where you were just re-writing the code as a comment and getting a green tick instead of a red "more comments!" note. I legitimately believe that my educators just didn't know any better themselves. These days I live by the mantra: Comment to explain WHY not HOW, since the WHY is lost to time whereas the HOW is often self-descriptive. PS - [0]Still my favorite comment of all time. I'm still pissed that someone tried to remove it from the article on Wikipedia (in particular as the comment is almost as famous as the code). [0] https://en.wikipedia.org/wiki/Fast_inverse_square_root#Overview_of_the_code https://en.wikipedia.org/wiki/Fast_inverse_square_root#Overv...
- longcommonname 5y ago
  How comments in school indicate to the grader that you not only can write code but you can explain what it's doing in another way. It's actually a somewhat decent way to catch cheaters. As it provides a better likeness score between two code comparisons.
- dkbrk 5y ago
  This obviously varies, but my experience was very different. I very distinctly recall being told in an introductory programming course: "Code is written for people, not computers." That really stuck with me. What that lecturer meant was that first and foremost code must be written to be comprehensible to other people. The particular techniques used, whether commenting, intelligent variable names, extracting sections into functions or using abstractions are just a means to that end. And layers of abstraction or indirection can easily harm comprehension rather than help. It all comes down to the circumstances. Do whatever is necessary to make it as comprehensible to other people as possible; everything else is secondary.
tonteldoos 5y ago
A number of people have touched on the fact that comments (even 'obvious' ones) provide boundaries, context and intent. I very much agree with this, with a couple of additional comments somewhat particular to embedded development: - Compared to most user facing development, where probably >75% of code is purely for interaction (and potentially more repetitive, obvious, and readable), a LOT of embedded code is not so readable, and quite often context is key. Good comments (even on apparently obvious code) almost always carry some context (why do this here, and why in this order, why the specific delay before reading the ADC, etc) - Because almost all the code is in some way business logic, it is definitely easier at times to read the flow of comments, rather than work out directly from the code which register someone is trying to set, and why, or why some seemingly arbitrary value is being incremented (that is actually being read by a parallel task somewhere else) - As always, good comments are as much for yourself six months from now, as for the guy replacing you 6 years from now. Sometimes, it is just a good way to document your thought process, as well as provide reasonably up to date system documentation, since ACTUAL design documentation almost always gets neglected. Basically - comment as much as you can, and as much as you need. Try and keep it up to date. It doesn't matter if it's seemingly obvious, or discussing the reasoning behind a particular architectural decision. Nobody I know has ever complained about too many comments, and if anything, more would have always been better.
- drran 5y ago
  One additional of benefit of commenting: if you cannot write comment for a block of code, then you either a) doesn't understand code well, b) code is useless and must be deleted. Most of the developers, which hate comments, hate them because they cannot write proper comments, i.e. they are hiding their own weakness, to look smarter than they are.
wyqydsyq 5y ago
> I find them useful as I write code because they allow me to state my intention (in plain English), translate it to code, then compare statements and see how well I’ve achieved my goal. IMO this is exactly what unit tests should be used for. Replace these comments with unit tests and you're doing TDD. The practical difference is by stating your intention as unit tests, you not only verify your initial implementation is correct but also that any future changes remain correct.
- rerx 5y ago
  If you are not careful, you end up with 1000s of tests that are tightly coupled to your implementation, testing internal details of your systems, not their behavior. They become a massive burden if you decide to refactor a system and change its internal implementation. Do test-driven development, but consider deleting these internal tests once you have scoped out how your initial implementation should work.
jkrubin 5y ago
Something I don't see mentioned at all is what I call 'div comments' which are solely for chunk organizing. I use something like the following quite a bit (in python/bash): # ============================================================================= # /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/ # ============================================================================= Doesn't give any hints about the codebase but (at least to me) it lets me see related blocks.
- leetrout 5y ago
  Sometimes a smell you should use multiple files or classes.
  - fbcpck 5y ago
    This is true, but sometimes it's not possible or awkward to do. I find myself writing such separator comment blocks in userscripts quite a bit; and stylesheets where I do not have any tooling attached to it (e.g. mediawiki css).
- fake-name 5y ago
  I use dividers like this because they're visible in the mini-map view that editors like sublime/vscode/atom have.
ajarmst 5y ago
When I teach coding, I used to have a similar lesson around commenting code: "don't tell me you're creating a variable. I can read the code. Tell me what the variable is for." I still mostly abide by that, but I've had an opportunity to write some larger programs for the first time in a few years (a hazard of teaching programming is you find yourself working with pretty small programs), and noticed that the comments started become a part of my conversation with myself. I'd drop in quick reminders for what I intended to do in a function before going moving on to something else. When I came back and then wrote the code corresponding to the comments: well now it's redundant, but it wasn't. I stopped cleaning that stuff up (I'd clean it if I had to present or publish it, of course). The comments kept some context of my thinking when I wrote it, what order I did things in, etc. It would be gibberish for another, but it wasn't for me, especially after a few days, or even longer. (Note: I'm a pretty fast touch-typist, so muttering to myself doesn't invoke much of a productivity cost. I also note that commit messages are another great place to capture that sort of context for yourself, and not using that opportunity is a sin.) So, I've changed some of my greybeard aphorisms around commenting: "When commenting code, consider the needs of the person who will be maintaining this code. Who will probably be you. Be nice to future you."
ping_pong 5y ago
I think it's stupid when people say they don't think code comments are good or necessary. It's a weirdly religious debate and frankly I think having a ton of code comments is great. Some of my closest friends think that all comments are absolutely unnecessary. We didn't work in the same code repos. I think 2 IDE features would make things easier for everyone: 1) have an option to remove code comments from view if you don't like them 2) tie a code comment to a piece of code and enforce it. If you change that piece of code, you should be forced to update and tied comments, or force to check that the comment is still correct. And have the fact that you approve a comment should be a part of the check in, so people can trace it.
- drran 5y ago
  1) Early versions of UNIX were shipped in source form with code comments stripped, for better readability and maintenability of the code. Google "obfuscation". 2) IMHO, it's better to assign a premium for the comment fix at GitHub. Your time is expensive, so it's better to outsource this distracting task to someone in India, because English is the official language in India. And track all that via a smart contract on a blockchain.
rhdunn 5y ago
I quite often use region/endregion comments to group methods of an interface being implemented, especially if a class implements multiple interfaces. The advantage of those is that an IDE/editor can collapse them and it is easier to see hat methods belong to which interfaces.
lordnacho 5y ago
I think the bar of usefulness for comments should be pretty low. Most modern IDEs will dim them for you anyway, so it's minimal how visually annoying it is. The problem is more that you might not have a comment when you need one. There's a lot of times when the author has thought a lot about something and thus understands it, but someone glancing over the code might not. Example: def caterpillarMethod(A, s): n = len(A) front, total = 0, 0 for back in xrange(n): while (front < n and total + A[front] <= s): total += A[front] front += 1 if total == s: return True total -= A[back] Someone reading this might think it's O(n*2), because there's a loop in a loop and that often makes it so. But if you look closely it isn't. So maybe comment that.
- nicoburns 5y ago
  Yep, and while I can understand what this is doing by going through it line-by-line, at a glance I haven't a clue. What is the high-level purpose of this function? This could be remedied with a few good comments.
Nimitz14 5y ago
99% of code is internal and something noone unexperienced will look at. If you're writing code for a tutorial for newbies then yeah, it makes sense to add obvious comments. But that's really it. The author is overstating his case.
- jeromenerf 5y ago
  I have the exact opposite point of view. 99% of the code is written by inexperienced people and passed on to the next generation that of inexperienced developers. Most development has been, is and will be for the foreseeable future outsourced, not in house. I don’t like that, but I have seen things. Too much comment about is never a severe problem. At most a distraction.
  - Nimitz14 5y ago
    You know what, I think you're right I should have been more specific. 99% of code that matters is written by experienced people in my opinion. I.e. the OS, the browser, your favourite apps, websites and programming libraries. Would you agree with that?
cjfd 5y ago
// Add a vertical scroll bar vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); This actually is helpful if a somewhat long list of components is being added. It makes it easier to find ones way in that list. Kind of like an index. So it really is not a useless comment. But there actually are useless comments. Like when people are told to explain every class member and one ends up with DatabaseConnection conn; // connection to the database This really is just clutter and the next problem is that it needs to be updated alongside the code. I once had a colleague advocating adding a comment for every parameter that a method has and then he would himself not update these if parameters were removed. That really is not very good.
bipson 5y ago
I can relate to where the author is coming from. What these comments do is give the code structure, and giving an outsider a better/faster view into the code, when he has no internal model for the library/framework/API/language which helps him recognize the statements (this outsider might be the author himself, or "future me"). Not knowing what these lines do, I can at first glance (i.e. skimming through the code) understand the author's intentions, what each line is responsible for. This is simply reduction of mental load and I even do this just for myself when trying to wrap my head around a new library or language. On the other hand, if you are writing for a (large) internal codebase, where you need to find a tradeoff between reduction of mental load and bloat, such comments can quickly become a nuisance... Then again, the cost of useless comment is usually much smaller than the cost of mental load (everyone knows how to ignore comments, unless they fill pages...) All this being said, I can only recommend "The Art of Readable Code" - Boswell [1]. [1] https://www.oreilly.com/library/view/the-art-of/9781449318482/ https://www.oreilly.com/library/view/the-art-of/978144931848...
rflrob 5y ago
I find the choice of the phrase “¿Como te llamas?” fascinating as evidence against “don’t do translation word for word in your head. ” Taken literally, “how (como) you (te) are called (llamas)” has no words in common with “what is your name”. The comments in the code would allow someone with a good Spanish vocabulary to actually translate into fluent English.
- dmurray 5y ago
  Yeah, it makes the complete opposite point of what the author is trying to say. Even as a beginning Spanish student, he didn't translate Spanish word-by-word, but phrase-by-phrase.
TrianguloY 5y ago
For me these comments are useful for two reasons: 1) If you know the author of the code (includes yourself) and you know their comments are a good indication of the code, you just read them and move along. No need to understand what they do. 2) If you don't know the author or you know their comments are often out of date (which you can check with git blame but let's ignore that) the comments tells you what the original intention was, and with an already mental model its easier to read code and understand what it's doing, even if it contains mistakes (in the worst case the code will have nothing to do, so it will be like if you had no comment).
uberswe 5y ago
I spend a lot of time reviewing code, I currently review every line of code for 16 other developers. Obvious comments are great for code reviews because it's a validation that what you intended to do is what your code actually does. From the article, the comment about adding a vertical scroll bar allows me to review the code and to check that it does indeed add a vertical scroll bar and not something else. Did the developer intend to require password lengths of at least 8 characters? A simple comment would tell me what the developer wanted to do and then I can verify that it was done correctly.
- b93rn 5y ago
  Great, but that's not the reason why obvious comments are bad. They are bad because it's not maintainable. For you this means that the next time a developer refactors the code, you need to check if the comment is still accurate with the refactored intentions. I repeat, this is not maintainable! I love how the book Clean Code described it: "A comment is a failure to express yourself in code." There are situation they are useful, but those are definitely not obvious comments.
  - NicoJuicy 5y ago
    Clean code of a guide, not a requirement. Eg. I like paragraphed comments, because you know what the next 5 lines will do and you can quickly skip to the part you need. It's not always possible to have a method with only 5 lines. There are use-cases where you want a big method doing a lot of things together, because it's complex. Eg. For a government project i needed to connect to the internal network for executing certain requests and all that logic was in one HttpProxyClass, shared between the api + service/deamon
    - b93rn 5y ago
      If those 5 lines do so much that you can't scan it quickly, why is it not in a function? I don't understand, why so many people here have a hard time of understanding this here on HN. You can't trust that comment, you don't know if its outdated or not. Update: I noticed you updated your comment. So my reaction to your addition is that a class can always be abstracted to higher level. It will probably do to much at this point.
tempodox 5y ago
The article makes some fair points. And once you move beyond the explaining-to-yourself stage, there's yet another reason to have such “useless” comments: quick code navigation. Finding the place in the code where X is being done would be perfectly feasible by consciously reading the code, but I want to save that energy. Letting my visual cortex pattern-match on a syntax-highlighted comment that looks a certain way is much cheaper and faster and can be done while scrolling through it without stopping. If you can make that comment so it's more useful beyond that, so much the better. Tricks like that come into play once you're past the language proficiency / commenting policy hurdles and feel the impact of your visual code design on your personal attention and energy budget.
- thrwaeasddsaf 5y ago
  As always, there's a flipside.. I find code with lots of comments and "fluff" to be a drag to read and navigate and generally work with. I would rather have less to scroll to begin with, than have comments help me jump to a specific spot. For example, I just replaced a well documented pair of functions that compute a checksum. The original implementation was about thirty lines, including comments and empty lines. My implementation uses a denser style and is just a single function with three lines in the body. I also removed a function argument to make the interface both simpler to use and also less general. KISS & YAGNI: if the more general version is ever needed, then it is trivial to add and make the simple version a wrapper for it. Until a real need shows up, I don't want it. Of course my changes go way beyond comments, but this kind of thing can make an order-of-magnitude difference in code size (as measured in lines). I would rather work with 300 lines than 3000 lines, and the reduced need for jumping/scrolling around lessens the importance of navigation aids. Also, I find that the aids that are there anyways (function names, etc.) become more useful when there's no fluff to render them ineffective.
  - drran 5y ago
    Why not just use an obfuscator? It produces clean and compact code. You can disable mangling of names and reformat code after obfuscation using a formatter with your own set of rules. IMHO, it better to use tool designed just for that, instead of performing obfuscation by hands.
goto11 5y ago
A tangential point is that the syntax coloring configuration in the editor should emphasize comments. If comments are de-emphasized (e.g. grayed out compared to code) you will get bad comments and comments out of sync with the code.
kyranjamie 5y ago
These examples aren't great. Functions have names for a reason. Use them. Comments get outdated quickly, people forget/are too lazy to update them. Much less likely in my exp. that someone will not change a fn name if it's behaviour changes. Comments should be reserved for non-obvious information. Github link, complex mathematics etc. Further, at what point does the relevance of a comment end? This ambiguity doesn't exist with a function. function addHorizontalScrollbar() { hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); } function addVerticalScrollbar() { vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); } function initializeScrollbarCaretPositions() { caretX = 0; caretY = 0; caretMemX = null; }
Yaina 5y ago
I'm a big fan of Short comments that describe a chunk of code – maybe 3-10 lines. Because a lot of times I don't really want to read all the code, I just want to get a more detailed sense of what the code is doing. I worked in the Firefox codebase for a while, and what I would have given for a simple comment that describes intentions or results; where instead I had to fire up searchfox.org and make a deep dive into some (equally sparsely commented) functions. There is some notion here, that these comments help new programmers, but I think as soon as your codebase is sufficiently big, there will be always parts you won't be familiar with, and these comments certainly help you scan over them quickly
- chowderman 5y ago
  Same here, I think small comments every 3-10 lines adds a lot of value, especially to large code bases. Being able to quickly scan through comments visually when you only need a high level overview of a chunk of code can take a 5 minute task of reading and understanding 50 lines of code into a 15 second task of reading and digesting a few small comments. Also, I'm curious to see how your experience was working on the firefox code base. I haven't checked out the code base myself, but have built from source a few times. Curious to see how the Rust progress has been going on the code base and which parts of firefox are currently implemented in Rust.
  - Yaina 5y ago
    Firefox is still largely C++ and Javascript and that's not going to change anytime soon. But it makes sense, because mostly you're adding or changing stuff that's already deeply connected with all the existing code. I think you see Rust when there are really big projects that can be treated as a library. For instance the network team is writing their QUIC implementation in Rust – called neqo – and I can imagine that this was possible because it's low level enough and separate enough from the rest of Firefox. It's of course also a resourcing question. For instance the download-manager code in Firefox is a big, big mess and it's not really owned by anyone. But it works, is safe, and handles a lot edge cases. Rewriting this thing (even again in Javascript) would be an enormous effort, and that's true for so many parts of the code base that might benefit from rewrites. A rewrite would be nice, but there probably will always be more important things to work on.
skohan 5y ago
> I find them useful as I write code because they allow me to state my intention (in plain English) I have gone back and fourth on comments over the years, but currently I'm working on a solo project which has been in serious development for some time, and using comments in this way is really useful. Especially because it's a domain I haven't done a ton of work in before, I've found my workflow is often to create a few source files, type out in comments what the component should do, and bit by bit hone in on how that should translate into code. It's also great for placeholders: if I'm not ready to fill in an implementation yet, I can just type out a lengthy description in the function body, and when I come back a week later I can remember what the intent was.
- roland35 5y ago
  I do the same thing for any major block - write out steps 1) 2) and so on as comments to help keep the end goal in mind.
juloo 5y ago
I always try to write a comment that say "why" the following code is needed or what concept it implements rather than what it does in details. I would do // We allow scrolling in two directions hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); caretX = 0; caretY = 0; caretMemX = null; (I don't have much inspiration in this specific example)
SomeHacker44 5y ago
I probably end up with numerous "useless" comments in my code. That's because I write my code's doc string first (or JavaDoc or whatever), then write the body in English comments or pseudocode on rare occasion, then write the code beneath and between the conments that are my English plan. I will also write additional comments about anything unintuitive, complex or unusual, even slightly, because I know that the code will be read many more times in the upcoming decades. (I have code I wrote in 1994 in production at one company, and another hitting its 20th anniversary this year still in production. Do you even remember libg++? Me neither, but the code still uses it...)
temporallobe 5y ago
One of my guilty pleasures is writing code comments, even in places where it might be “obvious” about what that block or line is doing. To me, it’s less mentally taxing to read a plain language description of the logic than to decipher that by reading the code. Of course the caveat is that if someone modifies that part of the code and doesn’t update the description, then it could be confusing. I much prefer this to the culture that seems to prevail among some languages (such as Ruby) that the code should be self-documenting. It is also my experience that writing comments (even the so-called flower boxes, e.g., Javadoc/JSDoc) force me to think about what the code is doing and its readability to future maintainers. If I find myself having to over-explain the block, I might rewrite it or extract it out to a function or class, the name of which summarizes the intent, therefore eliminating the need for the comment.
ArtDev 5y ago
I wrote obvious comments to obvious code. No one else looks at my code but I do, a lot. The result is easy navigation of many many lines of code. The comments act as an index and summary to each section. When it comes to comments, be verbose!
toomanybeersies 5y ago
I agree in principle. If it takes more than more than a second to grok what a particular bit of code is doing, it should have a comment (or be extracted into a method). However, in my experience, it's common for either: 1. Code to get changed, but the relevant comments are unchanged, or 2. Comments that are just as hard to understand as the code In both cases, it's even harder to understand the comment+code than if there was no comment at all

126 points by jerodsanto 5y ago

How, why, which, where, when, what, who. The code says how. The commit says what, and where the edited lines were/are in which files, when the edits were committed, and who committed them. The comments should say why, iff a why is needed.

tshaddox 5y ago

I sometimes use comments that are nearly as “obvious” as the examples, but more as a human-readable outline of the code block. The point isn’t to provide additional clarity after someone reads the code, but rather to be the first thing someone (especially myself, later) reads when encountering that code block.

gregschlom 5y ago

Fully agree with the author here. I write comments that "repeat the code" all the time, and I like to read them in other people's code. It allows the reader to quickly skim through large portions of code without having to fully decode each line. Obviously, I'm not talking about comment like this (which I see all the time): // adds 1 to x x += 1; That is certainly useless, even annoying. But a small comment every 2-3 lines to explain the following 2 to 3 lines is generally very useful.

themodelplumber 5y ago
It's funny to recall that when I was about 11 years old, 30+ years ago, I would have thanked you profusely for that comment, instantly unraveling the += mystery.
- dmurray 5y ago
  But in hindsight, it wouldn't be a good comment, because that information is misplaced. The perfect time for you to encounter that comment is the first time you ever encounter the += operator, not every time you encounter it. I generally think you shouldn't comment to explain your use of a language feature, even an unusual one. The exception: when there exists an idiomatic alternative which you intentionally didn't use, then a comment can explain why.
  - IlliOnato 5y ago
    ... or when the feature is counter-intuitive and actively confusing, like "oct" and "hex" operators in Perl that do opposite of what one not familiar with them would guess. Even after many years of programming in Perl I found comments like # FROM hex, not TO hex! useful.

whoisjuan 5y ago

I’m on the same page. Just look at the given example. Does it look wasteful to say that you’re adding a vertical bar when you have the following line of code?: // Add a vertical scroll bar vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); Perhaps. But the comment is making a lot more than simply describing what’s below of it. The comment is doing the following things: - It’s creating a visual boundary that aids to the readability of the code. It adds context within a large set of instructions. - It’s providing context that might not be there for the person who is reading the code. Just because you think the name of that function and what you’re passing into it clearly describes the instruction, doesn’t mean that everyone else does. At least not in a snap. The comment helps to reduce the cognitive load of reading the code because it’s explaining the instruction in plain english. - The comment itself could be part of a larger narrative that is trying to explain what that file is doing. It’s not there to make the obvious more obvious. It’s there to make the whole file obvious which is evidently important to write readable code. Look. I know there are purists that get offended with obvious code comments. But you cannot expect everyone to have the same proficiency you do. Writing good code, also means writing code that a newbie can at least comprehend. And sometimes that means explaining in plain english what could be already obvious to you. People like to think they are writing code like prose that is delightful to the reader, but many times are just writing reader hostile code. Write code focusing on clarity. Not elegance by obscurity. Make it clear, add structure, add visual boundaries. Ask yourself if what you think is obvious is obvious to everyone. If in doubt explain it with a comment. I’ll rather see an obvious comment and say “well that’s obvious” than spending valuable time trying to understand what certain piece of code is doing.

nitrogen 5y ago
Make it clear, add structure, add visual boundaries. And push back hard against linter/prettifier rules that remove all developer discretion from layout and structure.
- wilsonrocks 5y ago
  I'm all in on prettifying... If it's done automatically. I find it such a good tradeoff to not have to think about it that I'm happy to accept the times when I think my discretion would do it better. That said, I've started to develop strong views on some eslint rules. Usually around things being errors that should be warnings in development, like logging messages or debugger or unused variables. I like to run in CI with max warnings being zero to catch them then.

hcarvalhoalves 5y ago

IMO, if I feel the need to add comments to explain code blocks like this: > // Add a horizontal scroll bar > hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); > add(hScrollBar, BorderLayout.SOUTH); It's a sign I should be writing code that reads more like: > addHorizontalScrollBar()

cdubzzz 5y ago
Do you then document the new function, though?
- pixel_tracing 5y ago
  I think the function name is pretty self documenting, I would go a step further and make a function named addScrollBars() clear on its intention here
  - cdubzzz 5y ago
    Sure. Agreed. But I still docblock every function I write so this wouldn’t change much with respect to usefulness of the documentation.
- lkrubner 5y ago
  You've heard the XTreme slogan "Where you would write a comment, we would write a method"?
nitrogen 5y ago
If you're building a UI frame, like in this Swing example, I think it's reasonable to keep the code in a single method and separate it into functional blocks with comments. But the variable names and comments should still include a bit more of the why. Example: // Build the data table view ... // Add horizontal scroll bar to the data table view // This is needed if the table has more than N columns tableHScroll = // etc // Build the data navigation sidebar ... As an aside, I wish web UI programming was more like a declarative form of Swing (that is, a widget- and layout-oriented tree), rather than the current mess of React and a text-/document-oriented tree.

hvocode 5y ago

I write comments based on what I expect I will need to know if I close the editor and don’t look at the code again for a couple years and will need to jump back into it as quickly as possible. That usually means I don’t want to waste the time of future me reconstructing what the code denotes if I could just write it down in a comment in he first place.

jaggederest 5y ago

This is also somewhat about language choice. Languages more oriented towards natural language need less commenting. If I were writing C++ or assembler on a regular basis, I would probably be writing a lot of "what" comments. My favorite comments are actually "what" comments, but that clarify something opaque about the code, e.g. const R = 6371e3; const φ1 = lat1 * Math.PI/180; const φ2 = lat2 * Math.PI/180; const Δφ = (lat2-lat1) * Math.PI/180; const Δλ = (lon2-lon1) * Math.PI/180; const a = Math.sin(Δφ/2) * Math.sin(Δφ/2) + Math.cos(φ1) * Math.cos(φ2) * Math.sin(Δλ/2) * Math.sin(Δλ/2); const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a)); const d = R * c; It's extremely difficult to analyze that and say oh, obviously, that's the haversine distance formula, and the result is the distance in meters, of course. It would be slightly easier in a language with type annotations, but not a bunch easier. You add a simple // haversine distance formula, result is d in meters and now you can google the wikipedia page to understand the context and history.

BrissyCoder 5y ago
Modern C++ is actually quite readable now imo - fairly close to C#. Has come a long way in the last 20 years. That being said most code out there is legacy of course...
- jaggederest 5y ago
  Yes, I'm probably just traumatized from trying to look at 3d engine code "back in the day" :)
tharkun__ 5y ago
I imagine you will use this in more than one place in the code. Why does it need a comment? Naming the function should be enough for most of it. Other languages probably aren't better at specifying the "in meters" part either, are they?
- panopticon 5y ago
  A function still seems appropriate even if you're not using this multiple times. Unless how you're computing the haversine distance is relevant to the surrounding code, it would be much more readable to extract it out.

bdcravens 5y ago

I generally save comments for WTF code, or to put links that document what's going on. I try to abstract things as a lot of folks are mentioning here, but that just pushes things to another place. Eventually someone is going to need to debug that code. Here's a Puppeteer example, where text is being split into nodes to extract based on line breaks: /* https://medium.com/@roxeteer/javascript-one-liner-to-get-elements-text-content-without-its-child-nodes-8e59269d1e71 */ return await this.page.$eval(selector, e => { const s = [].reduce.call(e.childNodes, function(a, b) { return a + (b.nodeType === 3 ? b.textContent : ''); }, ''); return s.replace(/\s+/g,' ').trim(); });

ninthcat 5y ago
If you rewrite it so it's no longer a cryptic one-liner, it's probably easier to understand this way without a comment than the other way with one. return this.page.$eval(selector, (node) => Array .from(node.childNodes) .filter((child) => child.nodeType == Node.TEXT_NODE) .map((child) => child.nodeValue) .join('') .replace(/\s+/g, ' ') .trim() );
- dmurray 5y ago
  Hope this refactor was well unit tested, because it looks to do something a lot different from the original code.

mumblemumble 5y ago

The more I see people opine on commenting style, the more I want to just spam the "you do you" button and get on with my life. I have a way that I like to do it. Other people on my team have their own ways. My way is not hurting them. Their way is not hurting me. Either of us trying to impose our way on the other would hurt both of us.

deleted 5y ago
[deleted]

thirdplace_ 5y ago

This text reminds me of the fact that value judgements are personal and subjective. So, one man's benefit is another man's cost. To make matters worse, it's hard to do math with these things, thus net benefit can't possibly be calculated.

BurningFrog 5y ago

The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it. The never, ever happens consistently. So soon you have the "man with two watches" problem. The code says one thing, and the comments say another. You could fix it, and sometimes you spend that time, but inevitably you also stop reading the comments, since they're not reliable. I've never seen this not happen in comment heavy projects.

whoisjuan 5y ago
This is something you can quickly see with Git. If the comment lines are older than the code lines you can at least start with the assumption that the comment might be outdated. That’s more useful than dealing with stale documentation which can also be outdated. At least with code comments you have contextual proximity.
- tylorr 5y ago
  This sounds like a great idea for an editor plugin.
  - vSanjo 5y ago
    1. Iterate through all blocks of comments. 2. Determine if there have been updates within the block of comments first (one line of three updating, for example). 2. For each block of comments, find the proceeding block of code. 3. Compare the last update of comments to the last updates of the code. 4. Warn the user when it's over a threshold. Something like that?
l8again 5y ago
While that is true, it isn't a problem inherently with comments.
tablespoon 5y ago
> The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it. > So soon you have the "man with two watches" problem. The code says one thing, and the comments say another. You could fix it, and sometimes you spend that time, but inevitably you also stop reading the comments, since they're not reliable. When you think about it, function and variable names are comments. Should we not use those because they need to be maintained with the code?

l8again 5y ago

I always wondered if the "useless comment" comment was really a way of bragging employed by experienced programmers (or their wannabes). Why is it a burden on anyone? Most IDE clearly highlight the comments so you can tune it out. Also, even if it is obvious, at least when a bug presents itself, you don't have to spend much time figuring out the intention of the author and if it is indeed a bug or by design.

habeebtc 5y ago

Article mentions my preferred take: stating my intention to help keep me honest on what I am trying to achieve. Also: they function like an anchor tag. If you are spelunking a new code base for a specific functional area, a search in plain English would let you jump to the right spot more quickly.

dec0dedab0de 5y ago

My favorite comments are long winded apologies to my future self, or whoever has to work with the ugly hack I'm putting together to meet a deadline.

almostdeadguy 5y ago

For the most part I take no issue w/ the style of comments that act as a statement of intent. It only becomes a problem when comments are used to paper over the author's own indifference to making the code itself legible, and that's where I expect critiques like this truly come from. Comments without legible code do not help, as the comments are not a proof of correctness or verification that the author's intent has been carried out. You still need to read the code to understand the program. Code legibility is not unlike legibility in written language. Short sentences and paragraphs, clear transitions, well-defined hierarchy, consistent structure. Say more with less. Comments are often like footnotes: they elaborate upon the author's intent, provide a mental palette cleanser, elaborate on a digression in a way that limits distraction, or occasionally break the fourth wall. Comments are improper when they try to serve other means. For instance comments about invalid uses of a function/class/etc. when the type system can be used to prevent illegal usages of code. Or when comments are used to explain what is happening in extremely branchy, anti-modular, or otherwise illegible code.

Someone1234 5y ago

When I was doing CS in college, bad commenting was an academic requirement: As in your grade would be worse if you commented appropriately. Over multiple courses including software engineering, comment quality and or correct use of comments was never in the syllabus. But in several courses they wanted to see the code heavily commented, to the point where you were just re-writing the code as a comment and getting a green tick instead of a red "more comments!" note. I legitimately believe that my educators just didn't know any better themselves. These days I live by the mantra: Comment to explain WHY not HOW, since the WHY is lost to time whereas the HOW is often self-descriptive. PS - [0]Still my favorite comment of all time. I'm still pissed that someone tried to remove it from the article on Wikipedia (in particular as the comment is almost as famous as the code). [0] https://en.wikipedia.org/wiki/Fast_inverse_square_root#Overview_of_the_code https://en.wikipedia.org/wiki/Fast_inverse_square_root#Overv...

longcommonname 5y ago
How comments in school indicate to the grader that you not only can write code but you can explain what it's doing in another way. It's actually a somewhat decent way to catch cheaters. As it provides a better likeness score between two code comparisons.
dkbrk 5y ago
This obviously varies, but my experience was very different. I very distinctly recall being told in an introductory programming course: "Code is written for people, not computers." That really stuck with me. What that lecturer meant was that first and foremost code must be written to be comprehensible to other people. The particular techniques used, whether commenting, intelligent variable names, extracting sections into functions or using abstractions are just a means to that end. And layers of abstraction or indirection can easily harm comprehension rather than help. It all comes down to the circumstances. Do whatever is necessary to make it as comprehensible to other people as possible; everything else is secondary.

tonteldoos 5y ago

A number of people have touched on the fact that comments (even 'obvious' ones) provide boundaries, context and intent. I very much agree with this, with a couple of additional comments somewhat particular to embedded development: - Compared to most user facing development, where probably >75% of code is purely for interaction (and potentially more repetitive, obvious, and readable), a LOT of embedded code is not so readable, and quite often context is key. Good comments (even on apparently obvious code) almost always carry some context (why do this here, and why in this order, why the specific delay before reading the ADC, etc) - Because almost all the code is in some way business logic, it is definitely easier at times to read the flow of comments, rather than work out directly from the code which register someone is trying to set, and why, or why some seemingly arbitrary value is being incremented (that is actually being read by a parallel task somewhere else) - As always, good comments are as much for yourself six months from now, as for the guy replacing you 6 years from now. Sometimes, it is just a good way to document your thought process, as well as provide reasonably up to date system documentation, since ACTUAL design documentation almost always gets neglected. Basically - comment as much as you can, and as much as you need. Try and keep it up to date. It doesn't matter if it's seemingly obvious, or discussing the reasoning behind a particular architectural decision. Nobody I know has ever complained about too many comments, and if anything, more would have always been better.

drran 5y ago
One additional of benefit of commenting: if you cannot write comment for a block of code, then you either a) doesn't understand code well, b) code is useless and must be deleted. Most of the developers, which hate comments, hate them because they cannot write proper comments, i.e. they are hiding their own weakness, to look smarter than they are.

wyqydsyq 5y ago

> I find them useful as I write code because they allow me to state my intention (in plain English), translate it to code, then compare statements and see how well I’ve achieved my goal. IMO this is exactly what unit tests should be used for. Replace these comments with unit tests and you're doing TDD. The practical difference is by stating your intention as unit tests, you not only verify your initial implementation is correct but also that any future changes remain correct.

rerx 5y ago
If you are not careful, you end up with 1000s of tests that are tightly coupled to your implementation, testing internal details of your systems, not their behavior. They become a massive burden if you decide to refactor a system and change its internal implementation. Do test-driven development, but consider deleting these internal tests once you have scoped out how your initial implementation should work.

jkrubin 5y ago

Something I don't see mentioned at all is what I call 'div comments' which are solely for chunk organizing. I use something like the following quite a bit (in python/bash): # ============================================================================= # /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/ # ============================================================================= Doesn't give any hints about the codebase but (at least to me) it lets me see related blocks.

leetrout 5y ago
Sometimes a smell you should use multiple files or classes.
- fbcpck 5y ago
  This is true, but sometimes it's not possible or awkward to do. I find myself writing such separator comment blocks in userscripts quite a bit; and stylesheets where I do not have any tooling attached to it (e.g. mediawiki css).
fake-name 5y ago
I use dividers like this because they're visible in the mini-map view that editors like sublime/vscode/atom have.

ajarmst 5y ago

When I teach coding, I used to have a similar lesson around commenting code: "don't tell me you're creating a variable. I can read the code. Tell me what the variable is for." I still mostly abide by that, but I've had an opportunity to write some larger programs for the first time in a few years (a hazard of teaching programming is you find yourself working with pretty small programs), and noticed that the comments started become a part of my conversation with myself. I'd drop in quick reminders for what I intended to do in a function before going moving on to something else. When I came back and then wrote the code corresponding to the comments: well now it's redundant, but it wasn't. I stopped cleaning that stuff up (I'd clean it if I had to present or publish it, of course). The comments kept some context of my thinking when I wrote it, what order I did things in, etc. It would be gibberish for another, but it wasn't for me, especially after a few days, or even longer. (Note: I'm a pretty fast touch-typist, so muttering to myself doesn't invoke much of a productivity cost. I also note that commit messages are another great place to capture that sort of context for yourself, and not using that opportunity is a sin.) So, I've changed some of my greybeard aphorisms around commenting: "When commenting code, consider the needs of the person who will be maintaining this code. Who will probably be you. Be nice to future you."

ping_pong 5y ago

I think it's stupid when people say they don't think code comments are good or necessary. It's a weirdly religious debate and frankly I think having a ton of code comments is great. Some of my closest friends think that all comments are absolutely unnecessary. We didn't work in the same code repos. I think 2 IDE features would make things easier for everyone: 1) have an option to remove code comments from view if you don't like them 2) tie a code comment to a piece of code and enforce it. If you change that piece of code, you should be forced to update and tied comments, or force to check that the comment is still correct. And have the fact that you approve a comment should be a part of the check in, so people can trace it.

drran 5y ago
1) Early versions of UNIX were shipped in source form with code comments stripped, for better readability and maintenability of the code. Google "obfuscation". 2) IMHO, it's better to assign a premium for the comment fix at GitHub. Your time is expensive, so it's better to outsource this distracting task to someone in India, because English is the official language in India. And track all that via a smart contract on a blockchain.

rhdunn 5y ago

I quite often use region/endregion comments to group methods of an interface being implemented, especially if a class implements multiple interfaces. The advantage of those is that an IDE/editor can collapse them and it is easier to see hat methods belong to which interfaces.

lordnacho 5y ago

I think the bar of usefulness for comments should be pretty low. Most modern IDEs will dim them for you anyway, so it's minimal how visually annoying it is. The problem is more that you might not have a comment when you need one. There's a lot of times when the author has thought a lot about something and thus understands it, but someone glancing over the code might not. Example: def caterpillarMethod(A, s): n = len(A) front, total = 0, 0 for back in xrange(n): while (front < n and total + A[front] <= s): total += A[front] front += 1 if total == s: return True total -= A[back] Someone reading this might think it's O(n*2), because there's a loop in a loop and that often makes it so. But if you look closely it isn't. So maybe comment that.

nicoburns 5y ago
Yep, and while I can understand what this is doing by going through it line-by-line, at a glance I haven't a clue. What is the high-level purpose of this function? This could be remedied with a few good comments.

Nimitz14 5y ago

99% of code is internal and something noone unexperienced will look at. If you're writing code for a tutorial for newbies then yeah, it makes sense to add obvious comments. But that's really it. The author is overstating his case.

jeromenerf 5y ago
I have the exact opposite point of view. 99% of the code is written by inexperienced people and passed on to the next generation that of inexperienced developers. Most development has been, is and will be for the foreseeable future outsourced, not in house. I don’t like that, but I have seen things. Too much comment about is never a severe problem. At most a distraction.
- Nimitz14 5y ago
  You know what, I think you're right I should have been more specific. 99% of code that matters is written by experienced people in my opinion. I.e. the OS, the browser, your favourite apps, websites and programming libraries. Would you agree with that?

cjfd 5y ago

// Add a vertical scroll bar vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); This actually is helpful if a somewhat long list of components is being added. It makes it easier to find ones way in that list. Kind of like an index. So it really is not a useless comment. But there actually are useless comments. Like when people are told to explain every class member and one ends up with DatabaseConnection conn; // connection to the database This really is just clutter and the next problem is that it needs to be updated alongside the code. I once had a colleague advocating adding a comment for every parameter that a method has and then he would himself not update these if parameters were removed. That really is not very good.

bipson 5y ago

I can relate to where the author is coming from. What these comments do is give the code structure, and giving an outsider a better/faster view into the code, when he has no internal model for the library/framework/API/language which helps him recognize the statements (this outsider might be the author himself, or "future me"). Not knowing what these lines do, I can at first glance (i.e. skimming through the code) understand the author's intentions, what each line is responsible for. This is simply reduction of mental load and I even do this just for myself when trying to wrap my head around a new library or language. On the other hand, if you are writing for a (large) internal codebase, where you need to find a tradeoff between reduction of mental load and bloat, such comments can quickly become a nuisance... Then again, the cost of useless comment is usually much smaller than the cost of mental load (everyone knows how to ignore comments, unless they fill pages...) All this being said, I can only recommend "The Art of Readable Code" - Boswell [1]. [1] https://www.oreilly.com/library/view/the-art-of/9781449318482/ https://www.oreilly.com/library/view/the-art-of/978144931848...

rflrob 5y ago

I find the choice of the phrase “¿Como te llamas?” fascinating as evidence against “don’t do translation word for word in your head. ” Taken literally, “how (como) you (te) are called (llamas)” has no words in common with “what is your name”. The comments in the code would allow someone with a good Spanish vocabulary to actually translate into fluent English.

dmurray 5y ago
Yeah, it makes the complete opposite point of what the author is trying to say. Even as a beginning Spanish student, he didn't translate Spanish word-by-word, but phrase-by-phrase.

TrianguloY 5y ago

For me these comments are useful for two reasons: 1) If you know the author of the code (includes yourself) and you know their comments are a good indication of the code, you just read them and move along. No need to understand what they do. 2) If you don't know the author or you know their comments are often out of date (which you can check with git blame but let's ignore that) the comments tells you what the original intention was, and with an already mental model its easier to read code and understand what it's doing, even if it contains mistakes (in the worst case the code will have nothing to do, so it will be like if you had no comment).

uberswe 5y ago

I spend a lot of time reviewing code, I currently review every line of code for 16 other developers. Obvious comments are great for code reviews because it's a validation that what you intended to do is what your code actually does. From the article, the comment about adding a vertical scroll bar allows me to review the code and to check that it does indeed add a vertical scroll bar and not something else. Did the developer intend to require password lengths of at least 8 characters? A simple comment would tell me what the developer wanted to do and then I can verify that it was done correctly.

b93rn 5y ago
Great, but that's not the reason why obvious comments are bad. They are bad because it's not maintainable. For you this means that the next time a developer refactors the code, you need to check if the comment is still accurate with the refactored intentions. I repeat, this is not maintainable! I love how the book Clean Code described it: "A comment is a failure to express yourself in code." There are situation they are useful, but those are definitely not obvious comments.
- NicoJuicy 5y ago
  Clean code of a guide, not a requirement. Eg. I like paragraphed comments, because you know what the next 5 lines will do and you can quickly skip to the part you need. It's not always possible to have a method with only 5 lines. There are use-cases where you want a big method doing a lot of things together, because it's complex. Eg. For a government project i needed to connect to the internal network for executing certain requests and all that logic was in one HttpProxyClass, shared between the api + service/deamon
  - b93rn 5y ago
    If those 5 lines do so much that you can't scan it quickly, why is it not in a function? I don't understand, why so many people here have a hard time of understanding this here on HN. You can't trust that comment, you don't know if its outdated or not. Update: I noticed you updated your comment. So my reaction to your addition is that a class can always be abstracted to higher level. It will probably do to much at this point.

tempodox 5y ago

The article makes some fair points. And once you move beyond the explaining-to-yourself stage, there's yet another reason to have such “useless” comments: quick code navigation. Finding the place in the code where X is being done would be perfectly feasible by consciously reading the code, but I want to save that energy. Letting my visual cortex pattern-match on a syntax-highlighted comment that looks a certain way is much cheaper and faster and can be done while scrolling through it without stopping. If you can make that comment so it's more useful beyond that, so much the better. Tricks like that come into play once you're past the language proficiency / commenting policy hurdles and feel the impact of your visual code design on your personal attention and energy budget.

thrwaeasddsaf 5y ago
As always, there's a flipside.. I find code with lots of comments and "fluff" to be a drag to read and navigate and generally work with. I would rather have less to scroll to begin with, than have comments help me jump to a specific spot. For example, I just replaced a well documented pair of functions that compute a checksum. The original implementation was about thirty lines, including comments and empty lines. My implementation uses a denser style and is just a single function with three lines in the body. I also removed a function argument to make the interface both simpler to use and also less general. KISS & YAGNI: if the more general version is ever needed, then it is trivial to add and make the simple version a wrapper for it. Until a real need shows up, I don't want it. Of course my changes go way beyond comments, but this kind of thing can make an order-of-magnitude difference in code size (as measured in lines). I would rather work with 300 lines than 3000 lines, and the reduced need for jumping/scrolling around lessens the importance of navigation aids. Also, I find that the aids that are there anyways (function names, etc.) become more useful when there's no fluff to render them ineffective.
- drran 5y ago
  Why not just use an obfuscator? It produces clean and compact code. You can disable mangling of names and reformat code after obfuscation using a formatter with your own set of rules. IMHO, it better to use tool designed just for that, instead of performing obfuscation by hands.

goto11 5y ago

A tangential point is that the syntax coloring configuration in the editor should emphasize comments. If comments are de-emphasized (e.g. grayed out compared to code) you will get bad comments and comments out of sync with the code.

kyranjamie 5y ago

These examples aren't great. Functions have names for a reason. Use them. Comments get outdated quickly, people forget/are too lazy to update them. Much less likely in my exp. that someone will not change a fn name if it's behaviour changes. Comments should be reserved for non-obvious information. Github link, complex mathematics etc. Further, at what point does the relevance of a comment end? This ambiguity doesn't exist with a function. function addHorizontalScrollbar() { hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); } function addVerticalScrollbar() { vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); } function initializeScrollbarCaretPositions() { caretX = 0; caretY = 0; caretMemX = null; }

Yaina 5y ago

I'm a big fan of Short comments that describe a chunk of code – maybe 3-10 lines. Because a lot of times I don't really want to read all the code, I just want to get a more detailed sense of what the code is doing. I worked in the Firefox codebase for a while, and what I would have given for a simple comment that describes intentions or results; where instead I had to fire up searchfox.org and make a deep dive into some (equally sparsely commented) functions. There is some notion here, that these comments help new programmers, but I think as soon as your codebase is sufficiently big, there will be always parts you won't be familiar with, and these comments certainly help you scan over them quickly

chowderman 5y ago
Same here, I think small comments every 3-10 lines adds a lot of value, especially to large code bases. Being able to quickly scan through comments visually when you only need a high level overview of a chunk of code can take a 5 minute task of reading and understanding 50 lines of code into a 15 second task of reading and digesting a few small comments. Also, I'm curious to see how your experience was working on the firefox code base. I haven't checked out the code base myself, but have built from source a few times. Curious to see how the Rust progress has been going on the code base and which parts of firefox are currently implemented in Rust.
- Yaina 5y ago
  Firefox is still largely C++ and Javascript and that's not going to change anytime soon. But it makes sense, because mostly you're adding or changing stuff that's already deeply connected with all the existing code. I think you see Rust when there are really big projects that can be treated as a library. For instance the network team is writing their QUIC implementation in Rust – called neqo – and I can imagine that this was possible because it's low level enough and separate enough from the rest of Firefox. It's of course also a resourcing question. For instance the download-manager code in Firefox is a big, big mess and it's not really owned by anyone. But it works, is safe, and handles a lot edge cases. Rewriting this thing (even again in Javascript) would be an enormous effort, and that's true for so many parts of the code base that might benefit from rewrites. A rewrite would be nice, but there probably will always be more important things to work on.

skohan 5y ago

> I find them useful as I write code because they allow me to state my intention (in plain English) I have gone back and fourth on comments over the years, but currently I'm working on a solo project which has been in serious development for some time, and using comments in this way is really useful. Especially because it's a domain I haven't done a ton of work in before, I've found my workflow is often to create a few source files, type out in comments what the component should do, and bit by bit hone in on how that should translate into code. It's also great for placeholders: if I'm not ready to fill in an implementation yet, I can just type out a lengthy description in the function body, and when I come back a week later I can remember what the intent was.

roland35 5y ago
I do the same thing for any major block - write out steps 1) 2) and so on as comments to help keep the end goal in mind.

juloo 5y ago

I always try to write a comment that say "why" the following code is needed or what concept it implements rather than what it does in details. I would do // We allow scrolling in two directions hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); caretX = 0; caretY = 0; caretMemX = null; (I don't have much inspiration in this specific example)

SomeHacker44 5y ago

I probably end up with numerous "useless" comments in my code. That's because I write my code's doc string first (or JavaDoc or whatever), then write the body in English comments or pseudocode on rare occasion, then write the code beneath and between the conments that are my English plan. I will also write additional comments about anything unintuitive, complex or unusual, even slightly, because I know that the code will be read many more times in the upcoming decades. (I have code I wrote in 1994 in production at one company, and another hitting its 20th anniversary this year still in production. Do you even remember libg++? Me neither, but the code still uses it...)

temporallobe 5y ago

One of my guilty pleasures is writing code comments, even in places where it might be “obvious” about what that block or line is doing. To me, it’s less mentally taxing to read a plain language description of the logic than to decipher that by reading the code. Of course the caveat is that if someone modifies that part of the code and doesn’t update the description, then it could be confusing. I much prefer this to the culture that seems to prevail among some languages (such as Ruby) that the code should be self-documenting. It is also my experience that writing comments (even the so-called flower boxes, e.g., Javadoc/JSDoc) force me to think about what the code is doing and its readability to future maintainers. If I find myself having to over-explain the block, I might rewrite it or extract it out to a function or class, the name of which summarizes the intent, therefore eliminating the need for the comment.

ArtDev 5y ago

I wrote obvious comments to obvious code. No one else looks at my code but I do, a lot. The result is easy navigation of many many lines of code. The comments act as an index and summary to each section. When it comes to comments, be verbose!

toomanybeersies 5y ago

I agree in principle. If it takes more than more than a second to grok what a particular bit of code is doing, it should have a comment (or be extracted into a method). However, in my experience, it's common for either: 1. Code to get changed, but the relevant comments are unchanged, or 2. Comments that are just as hard to understand as the code In both cases, it's even harder to understand the comment+code than if there was no comment at all