There ware arguments like: "When you use Python you don't need to write comments because it is Self-documenting language". But is it really true? Or the "problem" in fact is only inborn human laziness? What is the purpose of comments?
Here is copy/paste fragment of C++ tutorial about... the comments.
At the statement level, comments should be used to describe why the code is doing something. A bad statement comment explains what the code is doing. If you ever write code that is so complex that needs a comment to explain what a statement is doing, you probably need to rewrite your code, not comment it.
Here are some examples of bad line comments and good statement comments.
// Set sight range to 0 sight = 0;(yes, we already can see that sight is being set to 0 by looking at the statement)
// The player just drank a potion of blindness and can not see anything sight = 0;(now we know WHY the player’s sight is being set to 0)
// Calculate the cost of the items cost = items / 2 * storePrice;(yes, we can see that this is a cost calculation, but why is items divided by 2?)
// We need to divide items by 2 here because they are bought in pairs cost = items / 2 * storePrice;(now we know!)
Programmers often have to make a tough decision between solving a problem one way, or solving it another way. Comments are a great way to remind yourself (or tell somebody else) the reason you made a one decision instead of another.
// We decided to use a linked list instead of an array because // arrays do insertion too slowly.
// We're going to use newton's method to find the root of a number because // there is no deterministic way to solve these equations.
Finally, comment should be written in a way that makes sense to someone who has no idea what the code does. It is often the case that a programmer will say “It’s obvious what this does! There’s no way I’ll forget about this”. Guess what? It’s not obvious, and you will be amazed how quickly you forget. :) You (or someone else) will thank you later for writing down the what, how, and why of your code in human language. Reading individual lines of code is easy. Understanding what goal they are meant to accomplish is not.
- At the library, program, or function level, describe what
- Inside the library, program, or function, describe how
- At the statement level, describe why.