If you have to write a comment to explain every definition, you've failed to make the code sufficiently readable and simple to understand IMHO. Code-level comme

If you have to write a comment to explain every definition, you've failed to make the code sufficiently readable and simple to understand IMHO. Code-level comments can become outdated without eagle-eyed code-reviewers. The code itself can never lie. Comments are a useful for explaining the implementation logic of a function or method, for instance. Or for generating API documentation. And file-level comments explaining the purpose of the class or module are always handy.