About code commenting

Greetings fellow coders!
I started a big coding project of my own a few months back and it´s got quite complex and lengthy.
Besides following naming convention to keep the code as readable as I can I found myself commenting the code a lot. I have description comments, reminder comments, to do comments all over the place… :sweat_smile: personally I find it useful to keep track of things in this large project.
However I keep hearing that comments are not good practice and that the naming convention and clean code should suffice.
I would really like to know your opinions about this.

Well good code explains itself, you achieve this by using logical variable and function names etc.

However this does not mean you should refrain from using comments. They could well be used to explain complex pieces of code, mark code sections.

Comments help the programmer in finding things and explaining the code back to itself after having not looked at it for some time. But also to explain the code to other coders who might have to work with it at a later stage in development. Or when the original programmer doesn’t work on it anymore.

Anyways, in this case you write the code for yourself, and you may do whatever suits you best :wink: .


Whomever has told you that is talking utter rubbish.

Unless we’re talking specifically about JavaScript, where excessive commenting (or otherwise generally driving up the file size) will have an impact, comments won’t impact your code too much.

If you’re using a compiled language, say C++, your comments are parsed by the compiler but they don’t end up in the final binary. As such the presence of comments may increase your compile time, but you shouldn’t see any real impact to the final program once compiled. I can’t think of any compiled language which would behave differently to this - though I am by no means an expert in all languages.

In short, if you’re commenting to make a block of code clearer or as a reminder of why you’ve done a certain thing in that way, go nuts. Trust me, when you go back to something after a lengthy period you’ll thank yourself - mainly because you won’t be sat there thinking “what the **** was I thinking here!?”.

Good documentation, in whatever form, should never be discouraged. :slight_smile:


like everything, i think its a balance.

Good code needs less comment because the code explains itself. However, there are very few people who’s code is so good, they don’t need any comments at all.

On the other hand, i think too much comments is also not good. If you have something like:

# declaring variable with integer value
my_int = 5

the comment is just not helpful, maybe a bit of an extreme example, but hopefully it gets my point across.

so i would generally recommend comments, it helps new developers who are joining the project, and you help yourself if you ever have to make changes to project after not working on the project for a long time

What is also find helpful are tests, because tests can (if written properly) tell you something about how the code is suppose to work/behave. Especially with more complex pieces of businesses logic.

disclaimer: this answer might contain personal opinion/preference.


Guess I’m on the right track then… :smile: :+1: