8 ms·

> Same way comments are extra weight that should only be in public or algorithm/need to know areas. Unless you are writing completely brilliant code your futur

• Mithaldu 9y ago
  Comments are not documentation. Documentation explains HOW to use a thing. Good comments explain WHY a thing is strange. Bad comments explain WHAT a thing does and must be made redundant by extracting and naming the thing.
  • titzer 9y ago
    > Comments are not documentation. Probably overly generalized to be pithy, but no. Comments are by very definition documentation, which can and should cover of all of the what/why/who/how/where. Documentation that occasionally explains how to use code can actually be useful! Unless you actually get around to writing a user manual (which gets out of date), please do consider documenting how something should be used, particularly in libraries.
    • Mithaldu 9y ago
      As a Perl developer i mean this literally and transfer it to other languages as well. POD (or a block comment above a function) describes the API and use cases of the function. Inline comments inside the function exist only to provide explanation for the next maintainer when they see a strange construct. Any other type of comment needs to be refactored. Also, i never said documentation isn't useful. HOW and WHY are useful. WHAT in documentation and comments isn't because it should be in the variable/function/method/class/instance name. (Who/Where/When are covered by the source repository and the blame function.)
• fouc 9y ago
  Only "brilliant" code ends up needing comments. Plain code organized into understandable methods (usually no more than half a page of code), with good naming for variables & method names reduces the need for comments. It's also easier to scan/read code if there's a minimum of comments in the way.
  • vanderZwan 9y ago
    There is a ton of code that only exists because of issues elsewhere in the code. This is the opposite of brilliant code: these are the dirty patchworks, the hacks glueing the whole thing together. Yet often these hacks are necessary, at least until some bug is fixed elsewhere. Clear, self-documenting code is great but it can't capture that holistic insight into what the whole program is doing. It can't capture context, because the whole point of clean refactored code is to be as context-free as possible.
    • scott_s 9y ago
      Completely agreed. Put another way: the sentiment that code documents itself is only possible in purely logical systems with no edge cases or surprising consequences. As an example, our code base has a comment which refers to our internal issue tracker which itself refers to this HN comment: https://news.ycombinator.com/item?id=9048947 https://news.ycombinator.com/item?id=9048947
      • dhimes 9y ago
        It's also only possible if the code is thought of as a text and is proofread/edited rigorously for reading. My process is 1) write the code quickly- add comments 2) revise for clarity and efficiency (usually modularity), remove comments as confidence allows. This is where I might get the variable and method names correct for self-documenting code. Usually it takes several passes. But most often, "good enough is good enough" and I leave comments in. Just in case.
      • vanderZwan 9y ago
        > which itself refers to this HN comment I was secretly hoping you actually meant your own comment, creating a recursive loop. But a surprise John Nagle is even better
• bgribble 9y ago
  IME it's the "completely brilliant" code that your future self will hate you for, and needs the most comments. Moreover, when the weight of those comments trends towards 50% being justifications for why you did it that way, it's an excellent sign that your code has gone from "brilliant" to "super-genius", as in "Wile E. Coyote, Super-Genius". "Completely dumb" code can be read by your future self without comments. Even, sometimes, by other people!
  • krylon 9y ago
    Sometimes, I have seen (and, on at least one occasion, written) code that was brilliant in its simplicity. Very clever, but at the same time completely obvious. (In the sense that one needed to be clever to come up with it, but it was easy to understand if somebody showed it to you.) But for the general case, I do wholeheartedly agree with you.
• zip1234 9y ago
  The problem with this is maintaining comments. If you are using a compiled language or even linting, code that is part of the codebased is checked by a machine at least in a cursory way and the code that is there is what runs. The comments are not guaranteed in any way to pertain to the code that is in the repo and there is not a way for a computer to check the meaning of the comment to make sure that it was updated to match the code. Comments can get out of date, which may make them do the opposite of what they are intended for.
  • IshKebab 9y ago
    > The problem with this is maintaining comments. That's like saying "the problem with healthcare is that it costs money". Of course comments can get out of date. The solution isn't to throw them out!
    • ajuc 9y ago
      There's no alternative for healthcare. There's alternative to in-code comments answering the question "why" - it's commit messages. They can't be out of date.
      • usrusr 9y ago
        But commit messages can easily get plowed under in some annoying "reformatted, I hate tabs/spaces" commit. I do like to see some "why" sprinkled in here and there that will survive those accidents. But I will nonetheless prefer blame output if it is still meaningful. Also, I enjoy a commit that removes redundant comments almost as much as one that removes redundant code.
        • vk23 9y ago
          You can either pass a commit id to git blame to see changes before the reformat happend or you can use git log like this: git log -L0,10:file.txt
      • TomMarius 9y ago
• ajuc 9y ago
  Comments that answer "what" are redundant. Choose your identifiers better. Write good commit messages and comments that answer "why" are redundant too. Commit messages by their nature refer to the exact code that they refered to when they were written. Comments answering "why" after a few years are misleading anyway, because code changed around them. Commenting public api etc is obvious, and most people do it.
  • scott_s 9y ago
    When you read through a part of your system that you've either never seen before or have forgotten how it works, do you also read all commit messages for all of that code? I'm asking because that's the only way I can imagine one can learn about the edge cases and surprising consequences in non-trivial systems if you have a rule about not using comments to explain them.
    • ajuc 9y ago
      No, I do a git blame, and see all the relevant commit messages. If there's not 1 line of code from that commit remaining why is it relevant? If something looks weird still - I go back to the commit that created this part of code and git blame that. I don't remember a case where I had to do 2 steps like that. BTW we have a rule of putting JIRA ticket numbers in commits, that makes it even easier to find out. You can see the whole discussion that resulted in the code you try to understand, test cases that you don't want to break with your new changes, etc.
      • gruez 9y ago
        >No, I do a git blame, and see all the relevant commit messages. sounds great until there's a refactor (including moving code around), then all the "comments" get buried.
        • macintux 9y ago
          It's a bit humorous that often the same people who insist the code should be enough documentation follow that up by clarifying that git, of course, supplies the rest. So something entirely outside the codebase, which may or may not be available to the person who needs the information, and which may or may not need to be extensively searched through years of history to find the relevant commit message, which may or may not be sufficient to explain the code... is better than having a comment in the code.
• imron 9y ago
  > your future self will hate you if you skimp on comments. Likewise, your future self will hate you when comments fall out of sync with the code. If the code is readable you don't need much in the way of comments.
  • ModernMech 9y ago
    Code explains what the program does. Comments explain why a program does what it does. Code and comments are orthogonal, not coincident.
• gwbas1c 9y ago
  My rule of thumb is, if I have to ask a question during a code review, the answer needs to be in a code comment.
• ropeadopepope 9y ago
  If I feel the need to add a comment to explain what I'm doing and why, then I usually take a step back and rethink what I'm doing and why. That urge tells me I'm trying to be too clever and that I need to simplify. I still add comments when I need them, but it's a rarity these days. Usually when I'm either on a time crunch or I can't think of a better way to do whatever it is I'm doing.
• xg15 9y ago
  I understand that as "document every class/module/public method with javadoc/pydoc/whatever and also explain the (few!) counter-intuitive bits of your code with inline comments. (You might find those deep within an algorithm, but usually not in plumbing or business logic code)." That should leave you with a solid documentation of your application's components and APIs and a small amount of inline comments. If you find you have more comments, either your code should be simplified or you're commenting trivialities. As everything, it's a guideline with exceptions, not an absolute rule.
• z3t4 9y ago
  Source control, eg the "comment" when committing code can also be used for comments.
• seanwilson 9y ago
  > Unless you are writing completely brilliant code your future self will hate you if you skimp on comments. The vast majority of comments I usually see can be rolled into variable names or function names. If you're writing lots of comments, that's a good indication your code is hard to understand, your variables are badly named and your functions are too long in my opinion. I think people that say "your code is bad if you don't have any comments" have things backwards personally. Pretty much the only time I use comments is when I'm forced to write weird code to workaround an API bug, to explain an unintuitive optimisation or to give high-level architecture documentation. I've honestly returned to code I've written myself maybe 5 years later and rarely had an issue that would have been helped with more comments.