8 ms·
The author touches on this a bit but I want to state this really simply: Codes needs "why" comments, not "what" comments. The "what" can be done by self-docume
by ElijahLynn 5y ago
The author touches on this a bit but I want to state this really simply:
Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why".
Write more "why" comments.
- Nicksil 5y ago>Codes needs "why" comments, not "what" comments. Indeed. While there are exceptions, "what" comments will usually only add noise thus making things more difficult. This isn't necessary: // Total count int total_count = 0;
- nicoburns 5y agoI find it's often useful to put a 'what commment' on a block of a few (2-10) lines of code. Then you can skim through the function without reading every individual line of code.
- isbvhodnvemrwvn 5y agoYou might as well be able to extract a method with a meaningful name then.
- ziml77 5y agoPlease no. Don't extract methods methods just to avoid using a comment. You end up making code more difficult to follow when you do that since you're now jumping somewhere else in the file and you're adding a lot of noise by having to pass the function's current state along as arguments to the new function.
- hackinthebochs 5y ago>by having to pass the function's current state along as arguments to the new function. But then the state being read and mutated by a block of code is explicit. The alternative is having to inspect the code to determine if and what state is being manipulated. The more code in a functional unit, the harder this gets.
- nicoburns 5y agoIf you're mutating variables then I'd agree that it might be best to encapsulate that in a function. But I'd argue that except for performance sensitive code, that's bad practice. The vast majority of code I write has 95% immutable variables. So even in a large function they'll typically be at most one or two mutable variables to keep track of (and very often zero).
- nicoburns 5y agoThat then makes the code non-linear, which IMO makes it a lot less readable in most circumstances.
- isbvhodnvemrwvn 5y agoIt depends, if it needed a comment in the first place it likely was at a different (likely lower) level of abstraction than the rest of the code in that method.
- nicoburns 5y agoYes, but that doesn't mean it doesn't benefit from being inline. I love being able to skim over the paragraph-comments to get the big picture and then dip into the details without having to jump to another file / part of the file and lose my context.
- firebaze 5y agoTo me it's actually faster and easier to read code instead. This is because i generally don't trust "what" comments - either I know the code already or I don't, and if I don't, then I don't trust the "what" comment fully, so I both have to parse "what" and code. A "why" comment usually ages well, so I generally trust it and can use it to better parse the code and its intentions. So I belong in the "what only for API methods" camp.
- nicoburns 5y agoDo you also read through every function call (at least the first time you encounter a given function)?
- bostonsre 5y agoI do something like this, but I write them as debug log statements so that you get the additional benefits from logging.
- nicoburns 5y agoYes, I've also done this in places. It works pretty well, although I wish I could get my syntax highlighter to de-emphasise these lines like it does with comments.
- majewsky 5y agoThis is Damian Conway's "coding in paragraphs" advice, and in my experience, it's the single best advice for more readable code. When you have a large function, split the code into blocks with a heading comment on each section. That way, you can skim through the function body quickly by just reading the headings, then dive deeper into whatever block you're interested in. Like section headings on an article.
- jbay808 5y agoWhat would be your opinion of this comment, though? // Reset the counter for the next run total_count = 0;
- latchkey 5y agowhy are you resetting the counter?
- dlp211 5y agoFor the next run. Why is in the comment, it's likely a design flaw though and no comment is going to help here. See comment about using proper scoping.
- rrose 5y agoit feels like this suggests a design flaw. You should probably be creating a new local `total_count` variable for each run that goes out of scope at the end of the run, rather than reusing the same variable over and over again in different contexts
- wongarsu 5y ago// reuse counter for performance, this brings 2% speedup total_count = 0; would be a quite useful why comment, if not creating a new variable each time is intentional
- rrose 5y agosure, but reusing an integer variable is never going to bring a 2% speedup. allocating a new variable of almost any type is not going to cause any performance issues, at least if it is allocated on the stack, and if the construction of the variable is particularly expensive, resetting it probably will be too. I would need to see a realistic example to believe that something like this would ever be a useful comment.
- 5y ago
- ithronmellon 5y agoWhat belongs in comments describing API methods, why belongs everywhere else.
- pc86 5y agoIf it's impossible to make "what" clear through the code itself.
- gbear605 5y agoIf a method is part of an API that might be used by developers external to your team, they don’t want to be looking through your code to figure out how to use your methods.
- iudqnolq 5y agoWith a public API it's important to distinguish "currently true from reading the code" and "promised to stay true through minor updates". What comments are useful for that
- CodeMage 5y agoThe point on API methods is incredibly important. True, "Why" is the most important kind of comment, but I disagree with the author's critique of the documentation-generating comments and agree with you. Yes, "what" comments are a source of additional developer effort and of possible inconsistencies between code and comments, but good API documentation is worth writing and maintaining. No matter how well you name your method and its arguments, if it's part of the public API and you don't include a comprehensive documentation comment, I'll be forced to dig through your source.
- jka 5y agoNicely said. One small adjustment I'd suggest -- because I care a lot about setting incentives -- is that we generally want not just _more_ "why" comments, but in particular concise "why" comments that empathize with and improve the life of future developers. They're a kind of message-in-a-bottle conversation.
- dcolkitt 5y agoI mostly agree with you, but there are certain cases where you’re making weird and non-intuitive performance optimizations and have to explain “the what”.
- aequitas 5y agoBut still you have to explain why your code is the way it is on top of that. You can always deduct the what from mentally processing the code, but you can't deduct the why, you only guess.
- ElijahLynn 5y agoDefinitely agree there are still cases where "what" is useful. Especially in some code that I come across that I just can't grok (e.g. badly named things), I start writing what it does just as a rubber duck method, and I don't have capacity to refactor the whole thing right then, at least I will leave behind a "what" comment because if I had trouble grokking what it does then someone else likely will too.
- kelnos 5y ago> _most_ of the time This is the thing that annoys me with arguments about all this. I will generally say "document the 'why' and not the 'what'; if the 'what' isn't clear from the code, fix the code to make it clear". And people will say "that's invalid because sometimes you really do need to do something clever and the 'what' needs to be documented" or whatever. And yes, that's fine! Stop taking everything people say as if it's an absolute, 100%-of-the-time statement! Obviously there are exceptions. That doesn't make the common-case rule useless or uninteresting. People should assume "most of the time" is the default implication about these sorts of "rules" unless otherwise noted.
- Normal_gaussian 5y agoThe funny thing is, when someone writes really 'clever' code, I need a why more than ever. Why isn't this simpler?
- bccdee 5y agoI think people often lean too far in favour of "self-documenting code," and "what" comments wind up being underused. The idea of self-documenting code is that the documentation is encoded in the function and variable names, more or less. Sure, extraneous comments should usually be avoided, but frankly, sometimes a couple sentences of plain English is just clearer. I'd rather people just tell me what's going on than try to squeeze it in to a few camel-case words if that would compromise the clarity.
- patrick451 5y agoWhen your coding standard enforces 80 characters, you end with a single logical statement split across many lines. This quickly approaches un-readability if you fetishize self documenting code. In my opinion, short variable and function names with a comments are often more readable that self documenting behemoths, e.g., double compute_angular_acceleration_in_radians_per_second_per_second(double torque_in_newtons_per_meter, double moment_of_inertia_in_kilogram_meters_meters); vs // Units are base unitsSI. double compute_angular_accel(double tau, double J); I'll take the second any day.
- adonnjohn 5y agoShould my 'why' comment go further than a Jira number?
- Normal_gaussian 5y agoAbsolutely. I worked a codebase that was littered with ticket numbers for a few years; many members of the team religiously added them but never read them. How do we know? Self hosted issue system and access logs. New starts would read a couple and that was it. A ticket is a really opaque way of showing something. If you click the issue you're now going through several tangentially related comments and a few MR back and forths just to work out if its even useful to you. People will stop bothering to even open the link unless they are really stuck. Whack a summary comment and then by all means include the link, but the comment is what most people will use.
- bostonsre 5y agoI wonder if there are jira integrations that would bring ticket info into the ide. Although, I hate jira and would definitely prefer good git commits.
- austinsharp 5y agoIntelliJ lets you expand links from patterns, so if in our codebase there's a BUGREPORT-12345 link, it's blue and clickable and goes to jira.
- nonameiguess 5y agoAbsolutely. All that information dies when your organization migrates off of Jira years down the line and the issue ids no longer exist.
- cmckn 5y agoYes. Unless your explanation is thousands of words (which it probably shouldn't be), just inline it. I only speak for me, but if I had to look up (potentially multiple) Jira tickets just to understand what was happening in a source file, I wouldn't be at that job very long.
- _bramses 5y agoWanna jump in here and say I'm working on this exact problem using GPT-3. The results when added to other dev tools have been really inspiring, and I'm learning how flexible comments can be when addressing the "why"[1] instead of just the "how". [1]https://replit.com/@bramses/stenography-carbon-bot#index.js https://replit.com/@bramses/stenography-carbon-bot#index.js