[asterisk_]

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