Why do programmers ask themselves, "What the F**** was I thinking" when they view uncommented code?

Factual Questions
21

I’m not a programmer, just a functional designer and parametrizer; IME the two most common mistakes when documenting parametrization are:

  1. doing it waaaay after the fact, when people have already forgotten why they did what they did, and often can’t even recognize what did they do,
  2. and not writing the "why"s of those parameters. A document saying “inspection type Z01A is created” is useless; I can look at the tables in the program and see that inspection type, and the Z tells me it’s non-standard… but why the fuck did you create it instead of using standard 01? Are there any settings in which Z01A differs from 01, or did you create it because you were afraid that using a standard value might cause the servers to explode? Is there any kind of business or technical reason to create Z01A? Will 01 also be used? If so, when will each of them be used?

The biggest strings of cursewords I’ve heard from programmers re. their own documents have also been surrounding the key question “but why?” The how of things doesn’t need to be documented anywhere near as much as the why.

22

I’m a big believer in code being readable without comments and often with new starters on our team I will give them a program and ask then to work out what it does, and how and why it works the way it does.

However I find myself writing more comments now because of the nature of what I am doing. Mostly we are doing BI stuff or creating adhoc reports to fill business needs. As most of the systems we are working with are poorly designed and either poorly documented or not documented at all, we include comments that explain situations like dracoi mentions. If the data values I am evaluating give you no clue as to why my program processes them in a specific way to save you having to dig up what I dug up, I will add a comment.

23

I don’t think I have ever written a comment as my basic ideology is that a programme should be written in such a way that it’s self-explanatory.

24

To those that argue that code should be self-explanatory: do you document your code?

Because clearly documentation is appropriate and useful for all but the most trivial of programs. And what’s the distinction between documentation and comments? Why is it valid to put information in one place and not another?

I find inline annotation a very convenient format when modifying or extending code.

25

Thank you greatly for that link.
Exactly the kind of retro-computing writing I love!

26

I don’t think in-line comments are necessary 90% of the time, the other 10% is usually due to setting up some kind of trickery or optimization to work around language or framework limitations, or if there’s approximately a bazillion ways to do something and you chose some odd way.

However, method/function comments are important. Any method that’s not really short, sweet, and self-explanatory probably needs to be commented with at least:

Any warnings or pre-conditions (i.e. “don’t use this in the recovery state or the world will end”), post-conditions (i.e. “parameters will not be modified”), any special non-obvious parameters (i.e. we know this int is called “date” but is it mmddyy? mmddyyyy? ddmmyyyy?), and the formatting and/or significance of the return value(s). Ideally it will also describe the function of the code.

However, I find that method and class comments should be left somewhat vague, in other words, not discuss implementation details. You really don’t want everybody worrying about the HOWs of your implementation unless it’s necessary. Nobody other than your supervisor should really care whether you used a linked list or array, “stores the data” is good enough and it keeps other people from using your code in a tricky way that makes it a pain if you find a good reason to change your implementation.

Of course, this changes in lower level code, all the way down to assembly, where code that’s REALLY basic in higher level languages may be several lines long. I don’t think it’s that out there in assembly to say “retrieve the string and modify the first character” if that’s going to be several instructions long (load, change, store, maybe update references), assembly is hard enough to read as it is.

ETA: To answer the OP directly, it’s not uncommon to learn new tricks, and coding isn’t always done on your best day. Sometimes you just want the damn thing to WORK, NOW. This can cause… problems, especially when you’ve been working on a completely different section of code for two months and forgot all the tiny little intricacies of that section that made you make those choices. It’s like reading a single paragraph of a poetry analysis, the interpretation may make sense right after you read the poem and all your reasoning leading up to that paragraph, but in isolation 5 months later it seems like inanity and insane logical leaps.