91–100 of 238 posts
Earlier quoted context omitted.
What belongs in comments describing API methods, why belongs everywhere else.
If it's impossible to make "what" clear through the code itself.
Earlier quoted context omitted.
// 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
sure, 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.
Earlier quoted context omitted.
>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;
What would be your opinion of this comment, though? // Reset the counter for the next run total_count = 0;
The contention is whether it is necessary or common enough to be assumed. In most places this would be self evident and should be avoided to reduce mental load, however I have seen and done exactly this many times - in distrubuted or embedded systems where the control is neither synchronous or co-located (ie, coming in from interrupts / messages). In such places there may even be call for more description, however presuming the context is appropriate this could be correct.
I would imagine a game with a react redux style state engine might result in a comment like this as well.
Earlier quoted context omitted.
To me it says that author is perfectly aware that people are not updating Javadoc comments or normal comments as well.
If your method documentation is out of date, the problem is not about the doc. The problem is that someone on your team drastically changes existing methods behavior instead of writing new ones, and by doing that, is changing the behavior every historical caller expected. I really think that if your changes are so important that they need the doc to be updated, it’s probably that you should write a brand new method.…
It is about people. In the world where team members last ~2 years and move on, expecting that documentation is left not updated is in my opinion perfectly valid assumption.
On the contrary, I find standard JSDoc and its variants to be an excellent tool for internal documentation. With hovering support in modern editors, it allows context explanation in a very streamlined and human way. The author mentions for preconditions to just “read the code”. I consider this bad advice. If using an external library, would you rather hover over the method and see its conditions, or would you rather…
nothing wrong with the tool, the issue is with the comments that exist and those that don't. getFoo() does not need a comment. if it does, (it shouldn't) and its JavaScript, JSDoc is a fine format. if getFoo() does need a comment, consider changing the code so it doesn't. Code is read much more often than its written: so be concise. If the docs can be automated by a simple tool, by definition, they were not necessary…
Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. So now I have…
If I come up with an inefficient algorithm that's short and readable, I tend to optimise it to something better but leave the reference implementation inside a code block.
(This goes without saying, but: I don't leave "commented code", but code inside comment, generally formatted with Markdown)
The only thing I would add is that header-style comments are immensely helpful for "chunking" the code into distinct sections. I first saw this recommended in Code Complete, and it stuck with me, since I've seen it in a number of other domains. It's a basic part of cognitive psychology that makes information processing and retention much easier.
Can you explain further what you mean by header-style comments? I'm having trouble drawing up a distinct example.
// --- Init ---
// --- Mainloop --
// --- Cleanup ---Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. So now I have…
When reading their code I'll add feedback to parts I don't understand (why do we need this cache invalidation, why do we use a worker pool here instead of throttling requests etc).
I find that questioning sits in the back of my mind when I write code - almost like a pair coder - to the point that I try to preempt questions like this by adding it as a comment.
Similarly for anything that's publicly accessible like public functions/properties/interfaces/classes, my goal for codedoc comments is to prevent the consumer (me or my team) from having to open the code to see what it does and how to consume it. If they can use it with just intellisense then it's a win.
Just like code readability and design, I'm seeing comments as another tool to communicate intent that can't always be communicated by code alone.
> If you wonder what the method does, or what the valid input range for a parameter is, you are better off just reading the code to see what it does. I couldn't disagree more. I was recently programming a library where some parameters could be 0 or greater, some parameters necessarily greater than 0, some parameters could be Infinity, others couldn't... Similarly, if one parameter is set to zero than another paramete…