7 ms·

Author here, thanks for posting. Here's some more color on the reflection on comments, straight from the Linux Kernel documentation that capture my intention m

• efsavage 5y ago
  The WHY is also very useful in comments, especially in business/UI/glue code where special cases abound.
  • klysm 5y ago
    I would say the why might be more important than the what a lot of the time
  • david-gpu 5y ago
    Came here to comment along those lines. The WHY often will be elaborate enough that it deserves a design document that includes things like: who is the owner of those requisites, what is the rationale behind them, who are the stakehilders who signed off, what interactions it has other components, what alternative designs were considered, etc.
  • dirkt 5y ago
    This. And in particular if there are multiple ways to do it, and you had to choose a particular way for a reason. Comments should explain the decision process (if one was necessary) that lead to this variant. Because if there's no comment explaining it, the next developer looking at it will say "oh, but it's much simpler if I just do it that way", and will run into trouble because he didn't realize the pitfalls.
• rgrmrts 5y ago
  Interesting reading about RuneScape in your post. I got into programming because of RuneScape and writing bots! Great memories. I enjoyed reading this post. Cheers!
  • rckrd 5y ago
    Thanks! Likewise. Truly a great sandbox for budding programmers.
    • mastersummoner 5y ago
      I got into programming at 14 because of writing scripts in Gemstone, a text based MMOMUD. Didn't even realize what I was doing was programming until college though...
      • calrizien 5y ago
        Gemstone! That game changed everything for me
  • AQuantized 5y ago
    Writing increasingly sophisticated bots and trying to figure out what exactly would earn you a ban was my own first practical experience with coding. I mostly managed to dodge bans on my most used accounts at the time, but interestingly when I checked back a year or two ago the majority had been permanently suspended. I wonder if they have some method of retroactively determining if someone was botting?
• Retric 5y ago
  The exception to the WHAT/HOW divide is working around a 3rd party bug. Documenting workarounds can help prevent reintroducing the same bug when someone edits or copies the code. This can be especially helpful if the 3rd party bug gets fixed in such a way that your workaround now fails.
• ajuc 5y ago
  > NEVER try to explain HOW your code works in a comment Never is a strong word, sometimes the algorithm is just inherently complex and it's worth it to explain what you are doing. Why is much more important, but it's also partially solved automatically by git blame and adding the task number to each commit message (and writing good commit messages which IMHO is more important than writing good comments). Each line of your code has commit message associated with it whether you care about it or not - make it useful.
  • bccdee 5y ago
    Yeah algorithms in particular are where I'm hesitant to say "never explain how your code works." They can be dense, deeply-nested, and hard to break down into semantically-meaningful variables and function names. Sometimes it's good to explain what's going on there.
    • Salgat 5y ago
      That's what people don't understand. We don't think in code, we have a translation layer from human language/thought that we think through when parsing a programming language. As long as the comments are kept accurate, they can greatly improve your ability to parse through a block of complex code, which is crucial when you're trying to hotfix an issue. It also gives newer programmers to the codebase a chance to help understand what that block of code is doing beyond it just being some blackbox with an input and output.
  • cjohansson 5y ago
    Yeah the how is important when auditing the correctness of code. I would say "Never listen to an advice about never doing something, there is always a case were breaking the rules is good"
    • deleted 5y ago
      [deleted]
  • vhakulinen 5y ago
    From the linked post: > Know when to break the rules.
• franciscop 5y ago
  Small typo, it's "Malcolm Gladwell in Outliers" not "Outsiders", I particularly noted it because I learned the word "outliers" in English thanks to that book.
  • rckrd 5y ago
    Thanks, fixed!
• juancb 5y ago
  What's your take on the difference between explaining how code works and describing what it does? I only ask because of bits like the TCP rate estimator sometimes have step by step comments that might be interpreted as explaining how the code is doing something. For example take the app limited detection function: https://github.com/torvalds/linux/blob/master/net/ipv4/tcp_rate.c#L182-L197 https://github.com/torvalds/linux/blob/master/net/ipv4/tcp_r...
  • mastersummoner 5y ago
    My take is that step by step commented explanations make sense when it's something either extremely complicated or making use of a system or tech that's not widely known. Otherwise, clearer code, smaller methods and better variable/method names are the way to go imo.
• mastersummoner 5y ago
  Another reasonable exception is referencing external sources - whether it's a specific library you borrowed code from, a piece of documentation needed to better understand what's going on, or a reference to a SO post explaining some weird workaround you've implemented.
• baconforce 5y ago
  I've seen this interpreted by smart engineers in a counter-productive way, in that they believe their code is so good that none of it ever needs any comments and hence they never write them despite the fact that their code isn't all that clear. It's more hubris than anything. Otherwise, there are many techniques you can use to make the code self-explanatory. I've taken a comment before and restructured the code to literally read like the comment.
• Clubber 5y ago
  The best comments are about intent. I can read the code and tell you what it does, but I have no idea if that's what it's supposed to do without knowing the intent.
• baby 5y ago
  > try to avoid putting comments inside a function body This makes me sad. Think about others who will have to reverse engineer your code. Not every functionality should be split into a function, unless you want to add 10 layers of abstraction and misdirection.
• dnautics 5y ago
  I think sometimes you want to put why in a comment. Just today I wrote a two paragraph comment (usually I don't write many comments at all) that describe the business need for why this the code is necessary (in my case, connecting to a 3rd party data source that overshares, describing the nature of the oversharing, outlining the -- very complex -- steps in the pruning algorithm, and noting that there are corner cases we might miss and also noting that we shouldn't care -- a handful of bad apples in a machine learning algo will probably disappear in the wash).
  • lugged 5y ago
    Yup, I rarely ask "what's this code do" or "how does this code do that". But "why the fuck" is a daily occurrence. Self documenting code explains how and what. If you need a comment to explain how and what its a code smell. Sometimes it's ok but ideally it should be rare. I try not to overcomment but when I write code that looks confusing or clever I try to explain why I've done it that way. If I'm optimising, I'll explain why. If I'm making an assumption about something related but elsehwere I'll explain that. If I'm leveraging some context that isn't explicit, I'll explain that. ... Also, type of code matters, glue code rarely needs exhaustive comments. Library code often gets line by line commentary so when someone comes in to change something for their use case they have a clear understanding of what they're really changing, and who and what might break because of their change. I notice library code tests often get more comments explaining what and why I'm adding an assertion. Glue code test rarely needs comments in tests.
• jbverschoor 5y ago
  Don’t agree. Longer pieces of code are way easier to reason about. Deep function nesting, which seems clean is very confusing mentally, and also difficult to describe in terms of function name. Explain *why* you’re doing something a certain way. This also includes a little bit of how and what. Other than that, just make sure your business terms are reflected in the code, or at least have a proper definition of things, which you can easily reason about.
  • cudgy 5y ago
    Agreed. When looking at complex code, it can be helpful to expand the functions inline to be able to view all of it in a single screen flow. Switching between too many files and functions sometimes creates friction, making it more difficult. However, when writing the code if a section of code is repeated more than 2 times, it should be considered to break it out into a separate function with a useful name.
    • fiddlerwoaroof 5y ago
      Unless you’re doing something like performance analysis, I think needing to peek into the definition of a function to understand a piece of code is a smell: it indicates that the function is only abbreviating and not providing an abstraction.
      • dragonsngoblins 5y ago
        Well a lot of the time when you are looking at something you are trying to diagnose some problem or another, which means you want to be 100% sure of what something is doing. Even if the function provides a good abstraction you might still want to make sure that it is doing exactly what it says on the tin because you are desk checking some weird behaviour and you want to make sure each step is acting correctly
        • fiddlerwoaroof 5y ago
          Agreed, but that means you verified that the use site was correct and are now examining whether the abstractions it depends on were implemented correctly. My point is just that you shouldn’t normally have to keep both sides of a call site in mind at once.
• 908B64B197 5y ago
  > tell WHAT your code does, not HOW And also Why. I personally like an executive summary of the code, ie, I just got to this file, what am-I looking at.
• hutzlibu 5y ago
  I prefer over-commenting a lot, over under-commenting. The only harm is, when you miss the important bits over too much blabla, or when you forget to update comments. There are not many worse things, than wrong documentation/comments. "you want your comments to tell WHAT your code does, not HOW" but I agree very much to this.
• ransom1538 5y ago
  "Comments are good, but there is also a danger of over-commenting." IMHO The only way to tell if you are able to comment well is to do this: Work on some project - then in 2 years come back to that project and add a feature to it. You will learn real quick how good your comments are. Spoiler alert: You wont care about "how" - you will want to know "why".
• hinkley 5y ago
  It’s an old assertion of the Refactoring community that a commented block in the middle of a function is a separate function trying to break free. If the code is interesting in its own right, move it. That also extends to how. If the algorithm is interesting or complex enough you should move it as well, as the point of the host function is not to show how clever you are, but to accomplish a task. Empirically I’ve found that I get much less pushback on algorithmic tweaks when I isolate them to a separate function. The reader doesn’t have to include them in their local reasoning, and I suspect but cannot prove that they tell themselves that they can always revert that code cleanly, so let’s just leave it be for now and see what happens.
• tpoacher 5y ago
  Define "comments". Like many arguments, disagreements below are mostly not disagreements about facts but disagreements of definitions at heart, only masquerading as disagreements about facts. Beyond a trivializing definition of "whatever follows a #", each time the word "comments" appears in the discussion below, it seems to actually refer to something entirely different from one person to the next.