In my projects (usually building websites or webapps) I therefore add a 'readme.md' to the root of the project and document general choices there.
In my projects (usually building websites or webapps) I therefore add a 'readme.md' to the root of the project and document general choices there.
Not only can you explain the why and demonstrate usage in a logical manner, but you get some consistency checks from your documentation for free.
You put them everywhere that might be relevant, along with cross-references to other relevant code/documentation. Humans aren't robots -- redundancy is a good thing, because it helps our feeble minds more quickly reinforce key concepts.
Obviously, redundant comments scattered across the code are even worse: out of sight, out of mind.
I think treating comments as something that's done in a separate phase is the wrong mindset. Comments should be integral part of code and therefore change whenever the relevant code changes.
Your first job as a professional programmer is making the rest of your team more productive by reducing the communication burden. Your second job is understanding old code. The amount of code you personally write is a distant third priority.
You're hitting on all the classic lame excuses. Self-documenting code is a myth, invented by lazy coders who would rather crank out code than write documentation, because it's more fun to write code. They're wrong, but they often don't know that they're wrong, because the same people who suck at writing documentation usually suck at reading code.
Clean code is a necessary, but insufficient precondition to understandability. Documentation is essential, because code can only tell you what -- it can't tell you where it should be used, why you should use it, how it should be used, who who should use it or when it's appropriate. And in any case, your code is never as clean or self-documenting as you think it is.
That said, I have no doubt that you're hearing these things from "experienced" coders, because our industry is filled with "experienced" people who suck at what they do. Also, these things are cliches for a reason. They get repeated a lot.
You can obviously get away with not documenting code, but you don't know what it's costing you. However well things are working out now, I can guarantee that they'd be working better and faster for your team if you spent the time to write good documentation.
You may think Martin Fowler is one of these "experienced people who suck at what they do", but you're likely to find yourself part of a small minority.
// foo library throws an extra two bytes at the front of the
// array, even though that isn't up to spec, so we have to
// strip them out here.