> I am in favour of trying to write self-documenting code, with clear unit and variable names, with an automated system to convert that to a human-readable form

> I am in favour of trying to write self-documenting code, with clear unit and variable names, with an automated system to convert that to a human-readable format. That's great and all, and I agree in principle, except time and time again I've witnessed people use the "my code is self-documenting" thing as an excuse not to describe anything they've written in plain English. Much of the time, it's pure arrogance of developers who think their shit doesn't stink. I'm not expecting people to litter their code with comments explaining what every line is doing. On the other hand, a project that can't even run on a dev's machine without having to repeatedly ask someone questions is unacceptable, and core architecture and concepts should be summarized so that new developers won't eff up or rethink ideas that have already been thought out.