[solved] Best ways to comment my code?

Question

What methods/strategies should I learn to have excellent code commenting?
Is there such a thing as "too much commenting"?
Should I delete previous versions, or comment them out?
Any other tips?

https://code.sololearn.com/c0q2B69E1GGM/?ref=app

Edit: I had searched the Q&A for: comment, commenting, comments. I should have also searched documentation
https://www.sololearn.com/discuss/394123/?ref=app
https://www.sololearn.com/discuss/1500376/?ref=app
https://www.sololearn.com/discuss/441080/?ref=app

Answer 1

You can never comment too much! Sometimes, when I write 5 lines of code that are particularly tricky and complicated, I'll write an 80 line comment explaining what it does, by posting detailed examples. Sometimes it needs to be done :p

For each function, describe what it does, what the parameters are, and what the return value is, above the function head.

// checks whether a given character is a vowel.
// returns 1 if it is a vowel, 0 otherwise.
int vowelch(char a) {
...
}

If you want to get really into it, you can adopt Doxygen commenting guidelines for C. It tells you how to write comments so you can automatically generate a manual from it. That's probably a bit too much to start though.

Not necessary: "end of func". My code editor will tell me that already. But if it helps you, keep it ofc.

About versions: Usually git will handle versioning for you, and you don't need to keep old code. Since you are not using git, decide for yourself: Will you likely need the old code later on? If no, throw it away.

Answer 2

Also important: Write code in a way such that it needs few comments. In other words, code should be self-documenting. Having a variable called `ow` will keep the reader guessing, calling it `vowelCount` would make it more obvious as to what is going on.

Though I understand that long variable names can be a pain if you're not in a proper code editor, and especially if you are coding on a phone.

Overall your comments are fine, I wish my coworkers would put half as much effort into their comments as you did. :P The most important thing is that something is written at all.