When commenting code, which of the two approaches considered good practice?
- Explain the content of the code, "translate" it to human - readable language, but not provide any explanation regarding why the code was written the way it is, why this and that part are necessary, etc..
- Explain the content of the code, as well as providing Explanations such as: why I use X and not Y, what design pattern do I follow when I do this, How can this part be used, etc.. (as well as what I mentioned above)
example of approach #1:
/*calling some_funct to do X and checking whether there have been any error*/ if(some_funct())...
example of approach #2:
/*calling some_funct to do X and checking whether there have been any error. Errors returned from the function are not printed to the user because the function prints its errors to the user from within itself*/ if(some_funct())...
So which one should I use? I believe the first approach to be more minimal and sometimes easier to read, while the second one seems more easier to understand.
In most of the docs I have seen right now the "no motivation" approach is more commonly taken, but this can be attributed to the fact I mostly use comments explaining the function itself and not the in - code comments which has more of an incentive to reason the code behavior.