Documentation
-
The documentation problem is one of software’s perennials. It remains unsolved.
Most shops don't practice meaningful quality control on their documentation. Inasmuch as external documents aren't part of the process that produces the executable code, they tend to drift away from the code over time -- a very short time. Rare is the design document that accurately reflects even the high-level structure of a significant program.
The ultimate solution would be the compilable specification: a requirements document that can be transformed by an automatic process into a design document, which could then be transformed by another automatic process into executable code. Drift would then be impossible. Unfortunately, the closest we come to that is well-commented source code in the language of your choice.
One of the most generous things a programmer can do for those who'll come after him is to comment his code meticulously and accurately. This, too, seems to be a dying art...encouraged into the mortuary by languages that purport to be "self-documenting." (That's among my favorite lies, right up there with "Meal Ready to Eat.") If you're a maintenance engineer, comment your code just as you would prefer that others comment their code for your sake...and if you're an originator, remember the agonies of your days as a maintenance engineer!
(This message is programming you in ways you cannot detect. Be afraid.)
Fran Porretto wrote:
One of the most generous things a programmer can do for those who'll come after him is to comment his code meticulously and accurately. This, too, seems to be a dying art...
Perhaps excluding the big iron era of which I don't have enough general experience to comment, then it never existed.
-
Fran Porretto wrote:
One of the most generous things a programmer can do for those who'll come after him is to comment his code meticulously and accurately. This, too, seems to be a dying art...
Perhaps excluding the big iron era of which I don't have enough general experience to comment, then it never existed.
jschell wrote:
Perhaps excluding the big iron era of which I don't have enough general experience...
No, don't exclude "then" either. In fact, a lot of programmers employed an "employment" guarantee technique (That never worked.) of writing incomprehensible code with no comments, so only they could work with their code. (gibberish variables, spaghetti code, dead sections of code.) You just learned to ask, "What is it supposed to do?" then follow it with, "What is it really doing?"
-
PHS241 wrote:
Have you ever wondered why compilers remove comments from the compiled output files? Because the compiler knows the comments would confuse it.
No. They remove them because the emitted code doesn't use them. Which is the same reason that it removes the symbolic names of local variables and does other things as well.
PHS241 wrote:
If you removed every comment from every source file you'd be left with 100% unambiguous code.
You must use different code bases then the ones I use. I often come across code, and just code, where the purpose is completely unknown (and unused), odd code, and that is only marginally correct.
PHS241 wrote:
Does anyone use it anymore? (tongue in cheek).
My feeling is the people do in fact use comments that are good. Which is why I provide good comments. I have received compliments several years after leaving a company on the commenting that my code had.
Guys....Hellooooooooooo.... Don't take me so seriously. That's why I ended my original response (tongue-in-cheek). Perhaps in a few years we'll have a compiler that can create code from nothing but comments. (Just Kidding).
"I do not have to forgive my enemies, I have had them all shot." — Ramón Maria Narváez (1800-68).