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...
PaulowniaK wrote:
Are you not supposed to be able to look up design documents to find your way around codes?
If the code is bad and incomprehensible, why do you expect it is different with its documentation?
It's an OO world.
public class Naerling : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
} -
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...
I don't really know how good your Japanese is but if you are noob at it, are you losing information in translation? If that's not the case then, design document was never updated after development was completed or it was made just for sake of getting a sign off to proceed to development. I would blame the people who reviewed and approved the document which does not serves the purpose. I there are decent comments in the code and can debug it without getting lost in tons of classes and methods, I would leave the document alone and try figure out from code. Another way to get around would be to look at unit test cases (if any).
"The worst code you'll come across is code you wrote last year.", wizardzz[^]
-
PaulowniaK wrote:
Are you not supposed to be able to look up design documents to find your way around codes?
If the code is bad and incomprehensible, why do you expect it is different with its documentation?
It's an OO world.
public class Naerling : Lazy<Person>{
public void DoWork(){ throw new NotImplementedException(); }
}Naerling wrote:
If the code is bad and incomprehensible, why do you expect it is different with its documentation?
As I say, the documentation is quite good. Just that I can't tie the documentation to the code... probably due to language barrier but I wasn't sure if I was trying something impossible.
Almost, but not quite, entirely unlike... me...
-
I don't really know how good your Japanese is but if you are noob at it, are you losing information in translation? If that's not the case then, design document was never updated after development was completed or it was made just for sake of getting a sign off to proceed to development. I would blame the people who reviewed and approved the document which does not serves the purpose. I there are decent comments in the code and can debug it without getting lost in tons of classes and methods, I would leave the document alone and try figure out from code. Another way to get around would be to look at unit test cases (if any).
"The worst code you'll come across is code you wrote last year.", wizardzz[^]
d@nish wrote:
I don't really know how good your Japanese is
Actually, Japanese is my mother tongue.
d@nish wrote:
I there are decent comments in the code and can debug it
Works to an extent, but too many interfaces, too many threads. It even crosses processes. My ickle brain hurts. X|
d@nish wrote:
Another way to get around would be to look at unit test cases (if any).
Ah! That'll be a different way of looking at things. I'll have a poke around in that direction then. Thanks.
Almost, but not quite, entirely unlike... me...
-
d@nish wrote:
I don't really know how good your Japanese is
Actually, Japanese is my mother tongue.
d@nish wrote:
I there are decent comments in the code and can debug it
Works to an extent, but too many interfaces, too many threads. It even crosses processes. My ickle brain hurts. X|
d@nish wrote:
Another way to get around would be to look at unit test cases (if any).
Ah! That'll be a different way of looking at things. I'll have a poke around in that direction then. Thanks.
Almost, but not quite, entirely unlike... me...
-
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...
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?"
-
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...
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).
-
Naerling wrote:
If the code is bad and incomprehensible, why do you expect it is different with its documentation?
As I say, the documentation is quite good. Just that I can't tie the documentation to the code... probably due to language barrier but I wasn't sure if I was trying something impossible.
Almost, but not quite, entirely unlike... me...
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.
-
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).
Compilers do remove comments, but they also generate useful debugging information, which I would argue is a sort of generated documentation. :) I take the opposite stance: if something is not documented, it doesn't exist. Maybe it's because I tend to work developing APIs, even ones that are used internally within the company. The end users in that case are developers, so you could make the point that they could just look at the source code (even just at function prototypes, class/interface definitions etc), but it's dangerous to do so, for two reasons: 1) It's a slow process when all they want to do is use your API; so they will ask a lot of questions, grumble about it being hard to use, and generally waste developer time with "how to" support requests. 2) They'll access protected stuff (especially in languages like Python where nothing is really private), or use stuff that I forgot to make private by mistake; then I change the implementation of a member, thinking that I have encapsulated it well, and I discover I have broken everybody's code, because they have hacked around my design. High level documentation should cover at least the use cases you intend to allow. Then your users are either satisfied with the documentation they've got, or if they're not they will file feature requests rather than hack about and find undocumented ways of using your software. For code documentation, I tend to use Doxygen which is great for producing reference pages. Yes, there's the issue of keeping documentation up to date, but code documentation is localised (especially if you use Doxygen comments). So the idea is: you changed that function? Review its Doxygen comment! You just allocate five more minutes for your task, and you save a new developer hours of trying to figure out what's going on. If you have a code review process, you can even make this part of the code review: the reviewer is an additional pair of eyes that can verify whether your change needs a documentation change. But this is just my opinion. :-) Do what works best in your company / for your project.
-+ HHexo +-
-
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).
