Does anyone use comments any more?

As an example, I do both hardware and software. I might work on FPGA code for months and then move on to the embedded code that runs the board. It is possible to not have to touch the FPGA code for months.

If I then have to go and modify something, say, add a register to implement a function I need, comments are a life-saver because you need to do a hard "context switch" in your head. I don't have time to read through code and figure out how a particular chunk-o-code works or what I meant by it. With FPGA code, where you are likely dealing with code structures that are controlling signals in the nanosecond range, you can't wing it. It either works or it doesn't and even minor code changes can make the entire thing go from working to a friggin mess. Comments are the "user manual" to the code.

Later on I might have to go and work on the iOS app that might access this hardware. So now you have FPGA code, embedded code (runs the board that has the FPGA) and iOS code.

Once again, even when I could be the only developer in the project without comments the entire thing becomes unmanageable very, very quickly.

What nonsense. In this age of syntax highlighting it's easy to make comments vanish in an editor; there's no shortage of screen space anyway; and if you find it insulting to have a guide to the function of the code, then maybe you're a little thin-skinned. Code is there to be maintained, not to serve as your mental gymnasium. It's a means to an end. Many skilled programmers may do fine without comments, but the above basically sounds like an excuse for not writing any.

You talk about over-commenting. I am talking about no comments whatsoever, not even to document methods or subroutines. I cloned this one project that was loaded with methods not used anywhere. In fact, it had included the SBJson framework and it was being used in a method that never got called. The issue came up because it collided with my own use of SBJson on my project and I wanted to figure out what to do about it. It turns out that I could just delete the entire thing and it did not affect the code at all.

I'll give you another example. I have not programmed in Forth in a long time. Maybe fifteen years. However, I do have tons of Forth code that I wrote back then for various projects. All of it is very well documented. I have no doubt that, fifteen years later, I could grab that code and be back in the swing of things in no time at all. I wouldn't have to read through the code in detail and go through the process of building stack images in my head to figure out what is going on. Without comments code libraries like that become impenetrable black boxes.

I could say the same about LISP. I haven't touched it in ages. I wrote tons of utilities and at least one major framework (one year dev time) for a variant called AutoLISP (runs inside AutoCAD). Again, tons of comments which would allow me to jump right in and know exactly what is going on.

It should go without saying that trivial stuff does not require comments. As an hypothetical example, a loop that searches an array (or whatever) for a specific match doesn't need line-by-line comments. What I might do here is, again, hypothetical, just before the "for" statement throw-in a comment that says something like "Look for CRC code match in packet data". With that simple line anyone reading the code knows what the intent was. I can read that code five years later and know exactly what it does without having to read backwards and forwards through the code to figure out what each variable might be, where they come from, what they are loaded with, what the intent might be, etc.

I also find it invaluable to document state machines (particularly for hardware --FPGA-- designs). If you take something like a custom DDR3 SDRAM controller state machine, well, it isn't a trivial thing to read through and figure out what it is doing. Well-authored comments can turn something that would take hours-upon-hours to comprehend into an easy read.

I have seen the value of good comments and code documentation many times over during my career. Keep in mind that I am not making a comparison between sparse comments and writing a book.

That comments get out of sync with code is a fact. That they stay out of sync is inexcusable. What I will generally do is to fully test and debug a chunk of code and then go back and annotate. I sometimes have a "Go comment the code" item in my to-do list and will spend time here and there cleaning-up and clarifying comments. The other interesting thing that can happen when commenting this way is that you can find issues with the code or identify refactoring opportunities.

It's like sitting down to explain what the code is doing to another capable programmer as opposes to a 12 year old who is just starting to learn how to program. Maybe that's the best way to put it. What do you say to an experience programmer if you had to do a code review and explain your code? That should go in the comments.

If a method or subroutine is absolutely trivial then you say "This finds the average of the voltages across these four inputs".

If, on the other hand, the routine is more complex, you have to describe the overall intent "this calculates the values of the missing pixels" and then dive within the module to explain some of the specific techniques being used "Polyphase FIR filter to interpolate image data for missing color samples" or "Bounds-limited adder to clip FIR filter data to legal image data range".

In other words, you don't explain every line of code but rather functional chunks that make it easier to navigate it and understand what is being done at a macro level and why.

Again, my peeve is with projects that have files upon files with not a single comment. I don't expect a book.

  int image_rows;
  int image_columns;

  // These variables will determine how the image is sliced.
  // They are bounds-limited in code to max values imposed by hardware and 
  // defined in configuration_settings.h
  int image_rows;
  int image_columns;