Reading the comments in a piece of code:
{
//Step 1 save stuff in a list
code();
//Step 3 Update the controls
morecode();
//Step 4 Resize the UI
somecode();
}

//Me thinking: where the f*ck is Step 2?

We don't talk about Step 2.... don't ask.

You don't want to know what happens there.

step 2 is AI, it killed itself

It is somewhere inside step 4

Actually there were 5 more functions with also missing step 2.. I just ignore these code smells..

//step 5

profit();

Thats why you should not depend solely on comments for understanding code ;)

They tend to become obsolete or broken.

As I read somewhere, comments can be used for why, not what. And personally I try to keep them as headers for functions.

In c# as in many others a method comment is used by intellisense and therefore adds extra info to the user of a function.

Step 2 is bit shifting the result of step 1 to the left.

code() << 1

Uncle Bob would be proud. And then sue you were copyright infringement.

// Step 2
// TODO: Remove this line to confuse devs.

@Voxera I literally will comment every line that isn't obviously self-explanatory. Most of it is "i'm so sorry this is such shit" at the start of bad code then walking through it, but y'know... i try.

@Parzi this might work on the first pass, but when your at the third or fifteenth modification comments usually start to differ quite a lot from the code, especially if there have been different maintainers over time.

I also used a lot more comments earlier but have moved to restructure code to be more inherently readable.

Like breaking out conditions in if to methods so I can have a name that describes what the condition is testing for, at least if its not obvious.

Replacing magic numbers and strings with names constants, braking out large loop bodies so the loop fits in one screen and so on.

This also makes it possible to put extra comments on the method explaining what it does if the name cannot be clear enough and also state any params and return value constraints that are not obvious.

Lately I have started with domain primitives from “secure by design” to move restrictions into the data classes to enforce valid values and move any error handling to where the value first appears instead of where I need it.

It means more code but also much more readable and easier to debug.

@Voxera Do... do people not update comments as code is changed???

@Parzi in my experience, no they do not.

At least mot diligently enough to keep them in good enough form.

The worst that could happen is if most are good so you start to trust them, then comes one where the logic is reversed and you end up destroying data permanently.

So I rarely trust comments within methods unless they are about the why.

Any “what” comments should mostly be redundant. But sometimes you need the why.

And why comments are less dangerous as they do not make promises about the code, rather excuses. And if why comments get out if sync it has less effect.

We have a sequence in our application which is printed in logs as Step 1,4,5,6. When asked, my manager replied, steps 2 and 3 are left deliberately to future-proof this application. There will be something here, we just dont know what it is right now.

And I was busy finding why those steps are not working.

Comments like this do more harm than they are useful.
Honestly stop doing this.
It is almost certain that the code will change and the comments become wrong hints and will only cause confusion.

Step two is deprecated.