Comments in Your Code

Today I will talk about comments in your code.

There is two kind of people for that.

  • The ones who comment everything in the code
  • The ones who comment nothing in the code

I will not say one solution is better than another, I will just try to explain (in my opinion) why we choose one or the other method and what are the benefits and the problems.

Comment everything

Pro:

  • No one can tell you didn’t comment enough your code (useful when you work in a big company and you have some tools to check if the code is well commented)
  • You can know quickly what your function do, what it will return, what kind of parameters are needed… (the same for your object)
  • You can give your code to someone, (s)he will understand what to use and how to use quickly
  • Really good to generate external documentations automatically

Con:

  • Difficult to read your code, when you have half code half comment you cannot focus enough on your code
  • Lose time for refactoring/maintaining of your code, when you have to change one function you also have to change associated comments
  • Really hard to maintain (yes again) if you forget to change one comment after refactoring or one bug fix this can be horrible because people will focus on the documentation and this one will be false
  • Temptation to write bigger functions/class because developers don’t like to comment, instead of having 10 functions of 2-3 lines (and 10 times 5 lines of comments) you will quickly have 1 function of 20-30 lines (and 1 time 5 lines of comments) even sometime a lot more…

Comment nothing

Pro:

  • Code is only code, you can just focus on your job
  • Easier to separate, because you have no comments you need to have functions/class quickly understandable and so reduce/split your code
  • Easy to detect bullshit code, when you think you have to put a comment to explain something, it means this part need to be re-factored
  • Force to have a clear code with full of meaning for variable name, functions name etc… forget about i, k, v…

Con:

  • Difficult for a new developer to understand how to use your code
  • Have to focus more on your code to have something clear (sometime spend more than one minute to decide the name of your variables)
  • Need to spend more time when you will have to create a full documentation (for a public API for example)

Of course this is only my opinion, perhaps you will not share my point of view and I will be happy to discuss about it, for me I don’t like to write useless stuff and comments are useless if your code is clear enough and when you decide to not comment you have to work more to have a code clear and easy to understand which is good when you want to refactor it. When you choose to code without comment you choose also to have a code better than ever.

Comments

Copyright © 2014 - Anthony Estebe -