Proper comments describe why... For example say you are using an api which requires guids and your application doesn't care are collisions as much so just use int id's.

You could add in a comment like

// creating a guid to interface with special api.

But just saying

// generate guid

Means nothing, your method should be generate_guid() or GenerateGuid(). Your comment is repeating.

Or this is probably going to hit my last company at some point, there was a system to read a serial number. They also wanted a "status" on the screen to verify the system was connected and running properly but both these values came over same signal wire. Depending on your exact ms timing sometimes you would read the status as the serial number. Another programmer wrote a check to verify the serial number did not start with OK. The comment added was

// add on 11/15/23 by Initials

With no other details. The serial numbers were 8 numeric digits. Someone won't know the history and delete this seemingly useless check and cause a 10s of 1000s of dollars in loss

[–] anomnom@sh.itjust.works 6 points 15 hours ago* (last edited 15 hours ago) (1 children)

I used to write it all the steps I thought I’d need as these types of comments, then go back and write the real methods. But I usually replaced the comments with more detailed jsdocs style comments with as much detail about the parameters as returnvalues as possible.

Then I quit web dev and moved to the woods.

[–] vrek@programming.dev 4 points 14 hours ago

Yeah effectively using comments as psuedocode