Comment Etiquette?

Hey guys I was finding my code really hard to read with all the comments in between every line so instead I did this:

https://i.imgur.com/qAPDwOW.png?1

It’s made my code much easier to read and I can separate the pseudo-code from the actual code in my mind.

My questions are.

  1. is this acceptable?
  2. is there any way to easily get the comments over to the right? (other than press tab 4-5 times)

The best thing would be to reduce the amount of comments.

Give your variables, parameters and functions meaningful names and you’ll find you can read and understand the code without comments.

In your image the only comment which is really required would be the Todo, most of the others are self explanatory by taking a quick look at the code.

A good article here: https://blog.codinghorror.com/coding-without-comments/

I understand the benefit but this advice seems to go against all other advice I have received regarding comments.

I am new at this but in my mind I think it all depends on why you are making the comments in the first place. Are you adding comments to remember why you did what you did? To explain to others who may use the script later? Is it for you and your learning process? Does you employer mandate a certain amount of comments for whatever reason? Or, for some other reason?

For me, it would really depend why I am making the comments. At this point of study, comments are only for myself so I don’t really care if I have too many. I tend to comment my code heavily as a learning tool. Hopefully, this will become less and less as I learn more. When I have the final coding done, I usually copy the entire thing and paste it into a text document and save it for future reference…maybe even add more comments. Once the text document is saved, I will go back into Visual Studio or whatever editor you use and delete any unnecessary comments so I have a clean script.

But, all this is just my personal opinion at this point in my learning.

Thanks for the reply.

For me at the moment I need to comments to understand my code, but at the same time I need my code to be easy to read to understand that as well!

Hi Simon

For me it’s a little too heavily commented, but having said that if you are just starting out on your coding journey or the comments help you understand what is going on the crack on with as many comments as you need. As you get more experience coding then you will find that the number of comments reduce naturally, especially if you use meaningful variable and function names.

Mike

2 Likes

Okay great! Thanks for the reply.

Privacy & Terms