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

That would depend on life-cycle expectancy, I guess. Our 2 current major systems (1 vfp, 1 PB) are about 5 years old, but we anticipate using them for a good 10 years longer, maybe even more, considering how far behind my agency is at downsizing some older systems from mainframe. But we all consider 10 years of "active system duty" worth serious documentation effort, as most of us plan to retire about that time and leaving decent legacy is considered fairly high-priority. So maybe "future-legacy apps" is a better way to put it, for future coders to have some idea what's going on in the current crop of apps..

Besides, for the really older apps, they still have the tiny naming restrictions, so no point at all in renaming those. All we can do is comment very thoroughly for these older apps, and await downsizing someday.


>>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."

Mostly, the top mgmt doesn't even know what "comments" are, with a few exceptions. I use a few simple rules of thumb on comments. If a fellow programmer who knows vfp still cannot understand my/our "self-documentation" method, than we need some additional comments, I didn't mean to imply "no comments at all." So I don't rule them out, just reduce the number of them, espcially the ones that merely tell you things you already know,we have a whole lot of those, and a rather large number written by outsource-programmers that didn't know much English. (we've all seen a lot of these, I'm sure, and they make the most important comments get lost in the shuffle. So, I say, comments are fine at times, but use them sparingly and always very meaningfully.

As an aside, a lot of the legacy code I've inherited are from when programmers were paid by lines-of-code, and those suckers stuck all manner of useless comments everywhere :-) That's really step 1, strip out all the nonsensical, linenumber-increasing comments added to produce larger paychecks :-)


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

As I said, the rules on comments come from me, not the top brass, they know virtually nothing on the subject except that making lots of comments and documentation sounds very good, but meanwhile contradicting this with "but sorry, we don't have the funding for it right now." You've heard this before, no doubt. So regardless of how I feel, I'm doing the best technique I can with limited resources as to documenting for future system developers and admns. I have inheritied and rebuilt enough legacies to know what's meaningful to me regarding comments, at any rate, a step ahead of the IT Brass. I'd give a rough estimate that 50% of older, legacy comments are worthless or confusing, having been a PL/I coder for many years.

>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.

Quite so, that's the one place where comments can really be invaluable.

>The same for a variable name.

I disagree on this. Though variables with 40-80 character length are a bit, ah, shall I say "awkward," to get accustomed to, they can describe their use extremely well. And they must always be declared, of course, regardles, of vfp's "non-typing" (might as well dump that "weakly-typed" jargon).

I also am discarding virtually all (vfp) arrays now, as cursors achieve a much better self-documentation, use long undertstanable names, and are rather strongly-typed when CREATEd. Arrays are black boxes, always needed in some languages, but only rarely in vfp (aside from some of the built-in ones), but generally, IMO cursors are better-suited to vfp.

>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.

Here's an item we can agree on. My rough guideline is that if a method spills over about two letter-sized pages, it needs division of tasks (occasional exceptions occur, but the rule works for the most part). And the reverse (merging many tiny methods into one larger one is of course nonsensical). And I do comment all methods at least briefly at the top, that's another principle I stick by. Even if they are very obvious what they do, you might want to comment what calls them, any incoming/outgoing parms, and lastly, when you print off methods, it's rather nice to have a title saying what you have printed on the hardcopy :-)

>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.

And that part we can agree on as well. This is my first experience where I actually get to fully make the lower-level calls on documenting several systems, midway through their life-cycles, but I'm still under the gun of what the top brass thinks is the latest good idea...

My suspicion is that they want to see stacks of hardcopy documentation and listings like the old mainframe days, not something practical like within-app documentation. Well, if so, I'm sure I can provide a zillion pages of what looks impressive to them! Enough for now, anyway.