>All documenation is a PITA, of course. But at my agency the top powers have decided we need more bureaucracy (er, I mean Documentation). For legacy reasons, if nothing else, I agree with the documentation ideas below.
>
>What I have decided on (having some degree of input on this, and I know a lot more than the top management about grunt-level coding), is to go back through current systems and rename massive amounts of things, now that there's no longer a pesky 8.3 or 10-12 char naming limit, etc.

While that makes sense in general, I don't really know whether it is worthwhile to invest lots of time into a legacy system.

>So we are renaming everything in all network/web systems: projects, classes, forms, objects, methods, tables, views, fields, variables, files, folders, everything under the sun, basically, with nice, long, very descriptive "self-documenting" names everywhere. (Adding only a few comments when really needed.) Basically, "comments" are "out-of-fashion", they are the "old-way" of doing things, and self-documentation is the "new way."

Clear names of course help, but I completely disagree with your bosses on comments being hardly necessary.

For instance, a function may have a descriptive name, but it may take several lines of code to describe in more details what it does, and perhaps a basic outline of how it does it.

The same for a variable name.

As for the code, if you divide your code into reasonably-sized section, giving each a short description (comment), your code becomes MUCH easier to read.

But you know all this, of course. The trouble is, perhaps, convincing people who have never done serious programming themselves, but think they know much better.