Please no, do not comment every function. Each function should average 5-10 lines, with clearly defined separation of concerns, and a descriptive name that inherently describes any writes/reads of the function. In the rare case where it makes sense to have a massive function, and you can’t break it into smaller functions within its scope, then maybe it makes sense to use a comment.
Adopting a policy of commenting every function header creates two major problems: (1) you now need to edit a comment every time you change a function, but your editor/compiler/rcs/ci will not inform you if you forget; (2) introducing a “typing tax” on creating new functions, since you need to write a comment too, actually discourages writing small functions because of the required comments.
The most readable code does not need comments, because you can clearly infer what each small function does by reading its header and local variable names. When looking at a set of functions, i.e. a class or file, you should be able to infer the “why” of each function by seeing it in the context of the other sensibly-named functions surrounding it.
Personally, my commenting policy is very simple: if I cannot infer the behavior of a piece of code by reading it, and I cannot change it to be more readable (usually for efficiency purposes), then I write a short comment explaining whatever is strange about it. This way someone reading through the code doesn’t need to slow down when they get to the grotesque portion, because they can just read the comment, assume it’s correct and double check later if necessary. Whereas if the code is littered with comments, you really can’t assume any are correct, which makes it difficult to read the actual code.
Adopting a policy of commenting every function header creates two major problems: (1) you now need to edit a comment every time you change a function, but your editor/compiler/rcs/ci will not inform you if you forget; (2) introducing a “typing tax” on creating new functions, since you need to write a comment too, actually discourages writing small functions because of the required comments.
The most readable code does not need comments, because you can clearly infer what each small function does by reading its header and local variable names. When looking at a set of functions, i.e. a class or file, you should be able to infer the “why” of each function by seeing it in the context of the other sensibly-named functions surrounding it.
Personally, my commenting policy is very simple: if I cannot infer the behavior of a piece of code by reading it, and I cannot change it to be more readable (usually for efficiency purposes), then I write a short comment explaining whatever is strange about it. This way someone reading through the code doesn’t need to slow down when they get to the grotesque portion, because they can just read the comment, assume it’s correct and double check later if necessary. Whereas if the code is littered with comments, you really can’t assume any are correct, which makes it difficult to read the actual code.