Documentation
-
I'm working on THE software that our department produces. It's rather hefty to put it mildly. There are spirits of the past programmers wafting about it. The thing's been going for ten years at least, maybe 20. It's been through a few incarnations and is still dragging around a pile of old baggage, not all of which are bad. The trouble is that not everything is properly commented, and some comments are out of date. Variable names and meanings aren't always clear and some morph through their travels through various modules written by different people. It doesn't help newcommers like myself getting around the code. So I turn to the vast pile of documentation, which are fairly detailed and organized. Problem solved? Not really... The documentation are in Japanese, but the code are (mostly) English. The Japanese documents tell me what the "thing" they're describing is supposed to do (and very well too). Just that the "thing" doesn't tie in with the actual classes and modules. What I want to know is "what is CComplicatedClass is supposed to do", but how do I find that out in a pile of documents that say "we are going to implement a useful class that does very complicated things". Am I going about this the wrong way? Are you not supposed to be able to look up design documents to find your way around codes? :~
Almost, but not quite, entirely unlike... me...
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.)
-
Detailed design documentation is generally a waste of time - if it's ever accurate, it never remains as such. This is part of the reason that Big Design Up Front[^] is so discredited. Hence I tend to think that in most cases you're better off with a high level design outline and a set of Doxygen style generated documentation. Although it's probably a smaller project (about 380k LOC) that's served us very well with Visual Lint[^] - the original product spec contains a high level design outline which is still valid 8 years after we started it. The only other code documentation is in the Doxygen comments, which are used to build a helpfile you can browse/search at will. This approach does of course assume that people comment their code as they go along. If they don't - that's a people rather than a documentation or code issue so it needs to be dealt with on that basis (training, review, slapping them around the head with a large rubber brick, etc.) rather than through piles of obsolete paper.
Anna :rose: Tech Blog | Visual Lint "Why would anyone prefer to wield a weapon that takes both hands at once, when they could use a lighter (and obviously superior) weapon that allows you to wield multiple ones at a time, and thus supports multi-paradigm carnage?"
Anna-Jayne Metcalfe wrote:
Detailed design documentation is generally a waste of time
I agree. I find it difficult to get it right in the first place. Keeping it accurate as the project evolves is even harder and depend too much on every person on the team and their discipline. Imagine trying to accomplish that on a big team project. I find it much easier to have properly documented code. In my C# projects I always enforce that the minimum amount of comment is the summary per property and + parameter description per method. This is easy to monitor and spot the undisciplined (rubber brick ready). That still leaves the functional spec documentation that I often see it's not updated as requirement changes. And this is usually difficult to tie to the code anyway.
To alcohol! The cause of, and solution to, all of life's problems - Homer Simpson ---- Our heads are round so our thoughts can change direction - Francis Picabia
-
I'm working on THE software that our department produces. It's rather hefty to put it mildly. There are spirits of the past programmers wafting about it. The thing's been going for ten years at least, maybe 20. It's been through a few incarnations and is still dragging around a pile of old baggage, not all of which are bad. The trouble is that not everything is properly commented, and some comments are out of date. Variable names and meanings aren't always clear and some morph through their travels through various modules written by different people. It doesn't help newcommers like myself getting around the code. So I turn to the vast pile of documentation, which are fairly detailed and organized. Problem solved? Not really... The documentation are in Japanese, but the code are (mostly) English. The Japanese documents tell me what the "thing" they're describing is supposed to do (and very well too). Just that the "thing" doesn't tie in with the actual classes and modules. What I want to know is "what is CComplicatedClass is supposed to do", but how do I find that out in a pile of documents that say "we are going to implement a useful class that does very complicated things". Am I going about this the wrong way? Are you not supposed to be able to look up design documents to find your way around codes? :~
Almost, but not quite, entirely unlike... me...
Get a copy of Enterprise Architect. It's probably the cheapest (less than $300 for a single license), and reverse engineer the code to some UML class diagrams. This way you can see how the code is put together and it will explain in some sense how your code is put together.
David
-
I'm working on THE software that our department produces. It's rather hefty to put it mildly. There are spirits of the past programmers wafting about it. The thing's been going for ten years at least, maybe 20. It's been through a few incarnations and is still dragging around a pile of old baggage, not all of which are bad. The trouble is that not everything is properly commented, and some comments are out of date. Variable names and meanings aren't always clear and some morph through their travels through various modules written by different people. It doesn't help newcommers like myself getting around the code. So I turn to the vast pile of documentation, which are fairly detailed and organized. Problem solved? Not really... The documentation are in Japanese, but the code are (mostly) English. The Japanese documents tell me what the "thing" they're describing is supposed to do (and very well too). Just that the "thing" doesn't tie in with the actual classes and modules. What I want to know is "what is CComplicatedClass is supposed to do", but how do I find that out in a pile of documents that say "we are going to implement a useful class that does very complicated things". Am I going about this the wrong way? Are you not supposed to be able to look up design documents to find your way around codes? :~
Almost, but not quite, entirely unlike... me...
PaulowniaK wrote:
Are you not supposed to be able to look up design documents to find your way around codes?
That would be the ideal way. Of course the comments would also reflect something meaningful. And the code would be meaningful itself (not just logically correct.) All of that is based on human factors and has nothing to do with technology. It comes down to having a process (humans doing stuff) that involves the following 1. Review the code 2. Review the designs 3. Insure code and designs correlate. 4. If 1-3 are not followed and followed in such a way that it enhances productivity then insure that developers are negatively impacted (for example no bonuses.) Many companies don't do any of the above. Many companies claim they do 1-3 (or one of them) but without 4, the actual work product of 1-3 is dependent solely on individual developers and many will not manage to produce even an adequate product. Notice in the above that I said "companies" and not "developers". Without active buy in from company leadership often at the VP or above level then the above will not happen. It will happen when middle level managers are penalized because their subordinates are not producing the above. I think that some companies manage it. However I have never worked for one. I have never interviewed with one and best that I can tell I have never heard of one indirectly. It is a big world though.
-
I worked on system once that had a huge stack of documentation, that was until we actually needed it and found out that it was for a completely different system. Some bright spark, when tasked with documenting the system, just took the docs from this other system and did a global replace on key words - and amazingly it was accepted.
You cant outrun the world, but there is no harm in getting a head start Real stupidity beats artificial intelligence every time.
-
Detailed design documentation is generally a waste of time - if it's ever accurate, it never remains as such. This is part of the reason that Big Design Up Front[^] is so discredited. Hence I tend to think that in most cases you're better off with a high level design outline and a set of Doxygen style generated documentation. Although it's probably a smaller project (about 380k LOC) that's served us very well with Visual Lint[^] - the original product spec contains a high level design outline which is still valid 8 years after we started it. The only other code documentation is in the Doxygen comments, which are used to build a helpfile you can browse/search at will. This approach does of course assume that people comment their code as they go along. If they don't - that's a people rather than a documentation or code issue so it needs to be dealt with on that basis (training, review, slapping them around the head with a large rubber brick, etc.) rather than through piles of obsolete paper.
Anna :rose: Tech Blog | Visual Lint "Why would anyone prefer to wield a weapon that takes both hands at once, when they could use a lighter (and obviously superior) weapon that allows you to wield multiple ones at a time, and thus supports multi-paradigm carnage?"
Anna-Jayne Metcalfe wrote:
Detailed design documentation is generally a waste of time - if it's ever accurate, it never remains as such. ... This approach does of course assume that people comment their code as they go along. If they don't - that's a people rather than a documentation or code issue
Of course it is a also a people problem if the design does not match the product. And the same fix applies.
-
Have you ever wondered why compilers remove comments from the compiled output files? Because the compiler knows the comments would confuse it. It's the same with us. If you removed every comment from every source file you'd be left with 100% unambiguous code. Devoid of comments, the code's current syntax is pure (bugs and all). Everyone can read C# but what it does is where the problems are found. How often have I looked at comments only to find the code it describes has changed to the point it bears little resemblance to the comments that described it. The answer is simple: scrap all documentation. Does anyone use it anymore? (tongue in cheek).
"I do not have to forgive my enemies, I have had them all shot." — Ramón Maria Narváez (1800-68).
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.
-
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).