Ok, I'll be the curmudgeon here. In recent software development efforts I have run, I have put for the rule that "All comments are bugs". Comments get separated from the code, make statements about obsolete activities, and often mislead the reader, and even sometimes the author. In place of comments, write code that is as self-explanatory as possible. I refer to Martin Fowler's "Refactoring" as a way of trying to inc…
What helps is using longer method/function/attribute/variable names
Sounds great, so why don't all good programmers do that? This is a deeper question than it seems. Over time, I've come to mostly prefer short names. The reason is that longer names add lexical noise to the code; they distort its structure and thus drown out other important information. The lexical is only one of several semantic channels and there are tradeoffs between them: you can't optimize clarity via verbosity. After a certain point (rather quickly, in fact) inflating the code detracts from clarity overall. It's easy to miss this because one often is making X more readable by giving it longer names or spelling its logic out in detail. The trouble is that other things than X have now become more obscure. The question is, what maximizes the clarity of the program as a whole?
I'm pretty sure my code would evoke howls from the "all code must be immediately readable [to me]" brigade. I used to feel the same way, but now I don't. It leads to sacrificing deeper comprehensibility (of the entire program) for superficial readability (line-by-line). Maximizing the overall clarity of a system is closely tied to distilling its parts, and the connections between them, to their minima. Code inflation inhibits this.
The demand for immediate readability comes from a belief that all code should reveal its secrets immediately. That would be great, except it's impossible. There's a fundamental complexity tradeoff at work. If you opt for verbose readability, you end up with code that is line-clear (I know this function is saving a record to a database or whatever) but system-incoherent (why the hell is it going to the database here?)
Talented programmers who care about readability but have a superficial view of what that is end up producing systems with far too much code. They accrete code, which may be impeccably pseudo-readable, when what they ought to be doing is distilling it. Such code is like the old joke about the person lost in a hot air balloon who calls down and says "where am I?", but the guy they're talking to is a technical person who answers, "you're in a balloon twenty feet above the ground".
Programs that are built for global intelligibility usually have much less code, but not necessarily the sort you can scroll to and immediately grok. You have to work to begin to understand the program, but once you absorb its conventions understanding proceeds much more rapidly. Latency is worse this way, but bandwidth is orders of magnitude better. The reader I feel responsible to is the one who is willing to put in this work. After all, they're going to have to do it anyway to get anywhere nontrivial.