Clarificatory comments, thumbs up! Code that requires an accompanying multi-chapter essay to understand, thumbs down.
Looks like about 150 words of comments there, not a multi-chapter essay.
That aside, I don't know what this code is doing, but working on sundry avionics software I would find that approximate amount of commentary very helpful in some situations. I would be remiss to downplay the value of this commentary without reading the actual words.
I agree with you, especially when you're writing low-level code which must interface with hardware or implement some protocol. However please allow me to play devil's advocate for just a moment.
First, incorrect documentation is harmful. So much so that in many circumstances I'd rather have no documentation than incorrect documentation. If all of your code has such a high comment-to-logic ratio you're either writing some really subtle (perhaps math-heavy) stuff, or you're introducing a bunch of potential for documentation issues.
Second, readability counts. If you feel like your code isn't understandable without a large number of comments, you've probably not written it to be readable. Sometimes this is very difficult to do (yes, I'm looking at you hot-path C++ code!) but I think that past a certain point effort can be better spent making the code easier to understand than on verbose documentation.
Agree. I have some complex code that I revsit once in a month, and I cannot afford thinking though it again and again. Therefore my comments are getting larger and larger and more chapter like with many images inbetween. (I use locco for that, see http://speedata.github.io/luaqrcode/docs/qrencode.html for a different but similar example.)
Depends on the comments. IMO comments together with the code should still follow the DRY principle - since code states exactly what it does, the comments should only state why it does what it does - except if we're talking about comments intended to be exposed to the documentation. Otherwise comments become outdated very quickly, ensuing confusion further down the line.
The most valuable comments that I've found are documentation as to exactly why the code is doing something that looks strange or wrong, on purpose. It keeps maintainers from going in and breaking stuff later.
Yes tests. But people can 'fix' tests at the same time too.
Except one, all those comments are on top of methods and the class. This can quite possibly be interface documentation. For a public API, this wouldn't be a lot of docs.
Clarificatory comments, thumbs up! Code that requires an accompanying multi-chapter essay to understand, thumbs down.
Looks like about 150 words of comments there, not a multi-chapter essay.
That aside, I don't know what this code is doing, but working on sundry avionics software I would find that approximate amount of commentary very helpful in some situations. I would be remiss to downplay the value of this commentary without reading the actual words.