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
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.
I sometimes suspect that I am actually an AI. I’ve always struggled with captchas and I comment my code exactly as you’ve just described.
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
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.
Yeah effectively using comments as psuedocode