5 ms·

I usually just consider my opensource commits to be 'learning opportunities' for others; so I comment on every other line. It's actually pretty nice as a way of

I usually just consider my opensource commits to be 'learning opportunities' for others; so I comment on every other line. It's actually pretty nice as a way of 'inlined duck debugging' that helps catch flawed reasoning, even when the code is 'obvious'. Example: https://github.com/Convery/Desktop_cpp/blob/VersionDD/Source/Appmain.cpp https://github.com/Convery/Desktop_cpp/blob/VersionDD/Source...

bwilliams 8y ago
I think that’s fine as a choice for a personal project, especially since your committed to it. It’s a totally different story when working with a team though. Comments become outdated, files get larger, and it becomes more of a hassle to maintain while providing little to no value most of the time.
- christophilus 8y ago
  Comments becoming stale is a real problem. But it is one that is solved by code review and culture, not by fewer comments. In a team setting, comments like these are even more important, as it gives context and higher level meaning to the code without forcing you to jump all over the place through small functions (which would be an alternative way to make this self documenting.
  - bwilliams 8y ago
    > comments like these I strongly disagree specifically about comments like these throughout an active code base. A well named variable or method can act as a much better descriptor of what’s happening and doesn’t have the same maintenance cost. I think we both agree that comments are valuable, just not the scope. Comments are valuable when you’re doing something unexpected or where the code fails to explain what’s happening. For what it’s worth I mostly work with Ruby, JavaScript, and TypeScript which definitely color my views.
  - jrochkind1 8y ago
    > Comments becoming stale is a real problem. But it is one that is solved by code review and culture, not by fewer comments. Well, it can be both. Less code is easier to maintain than more code, and that applies to comments too. Finding the "goldilocks" point is the challenge of much code design, and it applies to comments too. There's such a thing as both more comments than you need (increasing maintenance cost and risk of outdated comments without providing enough value to justify), as well as less comments than you need (to decrease cost of understanding the codebase).
VBprogrammer 8y ago
// 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...

bwilliams 8y ago

I think that’s fine as a choice for a personal project, especially since your committed to it. It’s a totally different story when working with a team though. Comments become outdated, files get larger, and it becomes more of a hassle to maintain while providing little to no value most of the time.

christophilus 8y ago
Comments becoming stale is a real problem. But it is one that is solved by code review and culture, not by fewer comments. In a team setting, comments like these are even more important, as it gives context and higher level meaning to the code without forcing you to jump all over the place through small functions (which would be an alternative way to make this self documenting.
- bwilliams 8y ago
  > comments like these I strongly disagree specifically about comments like these throughout an active code base. A well named variable or method can act as a much better descriptor of what’s happening and doesn’t have the same maintenance cost. I think we both agree that comments are valuable, just not the scope. Comments are valuable when you’re doing something unexpected or where the code fails to explain what’s happening. For what it’s worth I mostly work with Ruby, JavaScript, and TypeScript which definitely color my views.
- jrochkind1 8y ago
  > Comments becoming stale is a real problem. But it is one that is solved by code review and culture, not by fewer comments. Well, it can be both. Less code is easier to maintain than more code, and that applies to comments too. Finding the "goldilocks" point is the challenge of much code design, and it applies to comments too. There's such a thing as both more comments than you need (increasing maintenance cost and risk of outdated comments without providing enough value to justify), as well as less comments than you need (to decrease cost of understanding the codebase).

VBprogrammer 8y ago

// 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...