4 ms·

// Have the window rendering in the highest allowed state. I'd argue that comments like these are fluff. It says basically the same as what the code does but d

// Have the window rendering in the highest allowed state. I'd argue that comments like these are fluff. It says basically the same as what the code does but doesn't say why it does that. In general I find comments like that suffer from bit rot faster than anything else (perhaps with the exception of commented out code) as it's tempting to leave the comment changes until you've got something working. And a wrong comment can lead you down the wrong path very quickly.

convery 8y ago
Well, ye. I mentioned that it was mainly for less experienced users to learn what the code does; and in this case it also tells the reader what the thread is responsible for.
- asterisk_ 8y ago
  I get where you're coming from with the 'inlined duck debugging' observation, however I'm of the opinion that explicitly commenting out "obvious" code chunks is usually fairly detrimental for a few reasons: (0. The debugging approach can depend on a person's mental model) 1. Readability - even for a beginner, the method name should give a fair indication of what the code does. If the method name doesn't give a good indication, then the name should be changed. Otherwise, the comment is redundant. 2. Staleness - imagine a commit which changes the behavior of Engine::Compositing::onFrame(Deltatime) to only notify some of the components about the new frame (comment currently states "// Notify all components about the new frame"). Presumably, this commit should only change the internals of the onFrame method. However, because of a redundant comment, the person who changed the onFrame method now also has to find all its invocations and possibly update many comments. My personal preference is commenting only domain-specific code chunks (example: [1]). These code chunks are usually put as close to the implementation as possible. This way, whenever someone wishes to change the code, the person (1) immediately notices reasons behind the implementation (and may decide against modifying the code if he/she was unaware of these details) and (2) can modify the comment right away in case domain-specifics have changed in the meantime. I'm curious to hear your or someone else's opinion against this argument? [1] https://github.com/tkukurin/lesshint-intellij-plugin/blob/master/src/co/kukurin/LesshintOutput.java#L57 https://github.com/tkukurin/lesshint-intellij-plugin/blob/ma...
AlexCoventry 8y ago
> I'd argue that comments like these are fluff. It depends on who you're trying to reach. Since the GP wants his open-source commits to be "learning opportunities for others," it might make sense to comment in that level of detail. That particular comment does contain semantic information which is not expressed in the code: that the thread is being prioritized for rendering purposes. It's possible you could communicate that through variable names, though.
ummonk 8y ago
It's also bad to have overly detailed comments like this because it tends to result in code reviewers glossing over the code instead of checking what it does themselves. Generally, comments should focus on the "why", not the "what".

convery 8y ago

Well, ye. I mentioned that it was mainly for less experienced users to learn what the code does; and in this case it also tells the reader what the thread is responsible for.

asterisk_ 8y ago
I get where you're coming from with the 'inlined duck debugging' observation, however I'm of the opinion that explicitly commenting out "obvious" code chunks is usually fairly detrimental for a few reasons: (0. The debugging approach can depend on a person's mental model) 1. Readability - even for a beginner, the method name should give a fair indication of what the code does. If the method name doesn't give a good indication, then the name should be changed. Otherwise, the comment is redundant. 2. Staleness - imagine a commit which changes the behavior of Engine::Compositing::onFrame(Deltatime) to only notify some of the components about the new frame (comment currently states "// Notify all components about the new frame"). Presumably, this commit should only change the internals of the onFrame method. However, because of a redundant comment, the person who changed the onFrame method now also has to find all its invocations and possibly update many comments. My personal preference is commenting only domain-specific code chunks (example: [1]). These code chunks are usually put as close to the implementation as possible. This way, whenever someone wishes to change the code, the person (1) immediately notices reasons behind the implementation (and may decide against modifying the code if he/she was unaware of these details) and (2) can modify the comment right away in case domain-specifics have changed in the meantime. I'm curious to hear your or someone else's opinion against this argument? [1] https://github.com/tkukurin/lesshint-intellij-plugin/blob/master/src/co/kukurin/LesshintOutput.java#L57 https://github.com/tkukurin/lesshint-intellij-plugin/blob/ma...

AlexCoventry 8y ago

> I'd argue that comments like these are fluff. It depends on who you're trying to reach. Since the GP wants his open-source commits to be "learning opportunities for others," it might make sense to comment in that level of detail. That particular comment does contain semantic information which is not expressed in the code: that the thread is being prioritized for rendering purposes. It's possible you could communicate that through variable names, though.

ummonk 8y ago

It's also bad to have overly detailed comments like this because it tends to result in code reviewers glossing over the code instead of checking what it does themselves. Generally, comments should focus on the "why", not the "what".