You all would hate my code, and that's okay. Why? Because I do everything that is suggested, save one: I leave what comments in.
For some reason, it is easier and quicker for me to understand English prose than code, even if the code is simple. That includes checking the actual code after reading the comment to see if it matches; having a target for the code makes it orders of magnitude easier to read for me.
That said, I still weirdly find value in what comments. Even some of the simplest ones communicate intent for me.
For example, I have many comments that take one of the following forms:
// Cache this.
// Get the <item>.
These are the exact comments that people hate so much, but I like them because they communicate these things to me:
* The item is gotten for efficiency reasons. This means that I should check that it really is more efficient if something is slow.
* More importantly, the item is expected to not change, so if I'm digging aground for a bug, I should check that the item actually does not change.
So these "useless" comments actually help me.
In addition, the fear that they will go out-of-date is less of a problem for me because I have a strict habit of updating comments with code.
Now, I don't suggest that everybody do what I do; I suggest the opposite, in fact. But I work alone, so I can do things that were ideal for myself.
Yes: I find "what" comments critical. Naming things is hard; getting two people to agree on the concept the name represents is harder. I write "what" comments -- usually at a class, class field and method level -- religiously because it articulates the concept the class/field/method is supposed to represent. The whole point of writing code is to build a logical model of real-world concepts; if you can't articulate the concept, you can't write the code to model it. Sometimes these comments help others, but I find their greatest value comes when I finish writing the comment/documentation and compare it to the code. I often find that they don't quite match -- my code isn't doing what I just said it is -- and that forces me to either clarify the concept or fix the code. Either way, the model ... erm, system ... is better than it would be if I just relied on names alone.
For some reason, it is easier and quicker for me to understand English prose than code, even if the code is simple. That includes checking the actual code after reading the comment to see if it matches; having a target for the code makes it orders of magnitude easier to read for me.
That said, I still weirdly find value in what comments. Even some of the simplest ones communicate intent for me.
For example, I have many comments that take one of the following forms:
These are the exact comments that people hate so much, but I like them because they communicate these things to me:* The item is gotten for efficiency reasons. This means that I should check that it really is more efficient if something is slow.
* More importantly, the item is expected to not change, so if I'm digging aground for a bug, I should check that the item actually does not change.
So these "useless" comments actually help me.
In addition, the fear that they will go out-of-date is less of a problem for me because I have a strict habit of updating comments with code.
Now, I don't suggest that everybody do what I do; I suggest the opposite, in fact. But I work alone, so I can do things that were ideal for myself.