This should be the top reply! Just want to add my extra take on comments: Comments are absolutely necessary when explaining complex logic that is hard to read

This should be the top reply! Just want to add my extra take on comments: Comments are absolutely necessary when explaining complex logic that is hard to read for the casual reader (or yourself 6 months later). Comments are not necessary when the code itself explains what it does by being clearly named, isolated and organized. Comments are not documentation and shouldn't be used as such. They are tools to improve code clarity for the person who is changing the code. They are not tools for someone who is using the code. If the intent is to teach someone what the code does so they can use it somewhere else, write documentation in a wiki with examples and link the wiki URL to that point in the code.