Let This Be A Lesson To Us All
-
This is part of a reply I posted in the VC++ forum, but I figure it's something all of you might want to read and heed: ------------------------------------- There are aspects of this code that are INFURIATING, but the legacy is over seven years old. Like any other project I've been involved with over the last 15 years, nobody wants to pony up the bucks to make the code more maintainable by programmers that are new to the team. There's an almost complete lack of real technical documentation, and most of the guys that wrote the original code are LONG gone. Of course, in-source comments are non-existant in the most critical parts of the code, so the only vehicle we have is to review the source code one line at a time. I'm apprehensive about rebuilding the code unless we start from scratch because nobody is absolutely sure (and more often than not, not even remotely knowledgable) about how all the code interacts. It doesn't help when the code exhibits an eclectic coding style and non-adherance to anything that could be called corporate policy about how to write/format the code. Add to that an insane lack of use of MFC except when (apparently) absolutely necessary, and things start to get real whacked out. Finally, there's the issue of source code control. We use Visual SourceSafe, and most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. How absolutely stupid is that? What's funny is that we all agree that it needs to be fixed, but upper management would just laugh us out of the office if we suggested that we take the time to do so at our own expense (without having a "customer" to pay the bill). The effort would probably require the better part of a year (or more) just because we no longer have the original authors availble to us, and we lack the documentation that describes the architecture. Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation. "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation. Damn straight!!! And I fail at this too. :( Tim Smith I know what you're thinking punk, you're thinking did he spell check this document? Well, to tell you the truth I kinda forgot myself in all this excitement. But being this here's CodeProject, the most powerful forums in the world and would blow your head clean off, you've got to ask yourself one question, Do I feel lucky? Well do ya punk?
-
This is part of a reply I posted in the VC++ forum, but I figure it's something all of you might want to read and heed: ------------------------------------- There are aspects of this code that are INFURIATING, but the legacy is over seven years old. Like any other project I've been involved with over the last 15 years, nobody wants to pony up the bucks to make the code more maintainable by programmers that are new to the team. There's an almost complete lack of real technical documentation, and most of the guys that wrote the original code are LONG gone. Of course, in-source comments are non-existant in the most critical parts of the code, so the only vehicle we have is to review the source code one line at a time. I'm apprehensive about rebuilding the code unless we start from scratch because nobody is absolutely sure (and more often than not, not even remotely knowledgable) about how all the code interacts. It doesn't help when the code exhibits an eclectic coding style and non-adherance to anything that could be called corporate policy about how to write/format the code. Add to that an insane lack of use of MFC except when (apparently) absolutely necessary, and things start to get real whacked out. Finally, there's the issue of source code control. We use Visual SourceSafe, and most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. How absolutely stupid is that? What's funny is that we all agree that it needs to be fixed, but upper management would just laugh us out of the office if we suggested that we take the time to do so at our own expense (without having a "customer" to pay the bill). The effort would probably require the better part of a year (or more) just because we no longer have the original authors availble to us, and we lack the documentation that describes the architecture. Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation. "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
I am slowily learning this lesson, Last 3 title I have read are
- Debugging Applications
- Writing Solid Code
- Code Complete
Regards Ray "Je Suis Mort De Rire"
-
This is part of a reply I posted in the VC++ forum, but I figure it's something all of you might want to read and heed: ------------------------------------- There are aspects of this code that are INFURIATING, but the legacy is over seven years old. Like any other project I've been involved with over the last 15 years, nobody wants to pony up the bucks to make the code more maintainable by programmers that are new to the team. There's an almost complete lack of real technical documentation, and most of the guys that wrote the original code are LONG gone. Of course, in-source comments are non-existant in the most critical parts of the code, so the only vehicle we have is to review the source code one line at a time. I'm apprehensive about rebuilding the code unless we start from scratch because nobody is absolutely sure (and more often than not, not even remotely knowledgable) about how all the code interacts. It doesn't help when the code exhibits an eclectic coding style and non-adherance to anything that could be called corporate policy about how to write/format the code. Add to that an insane lack of use of MFC except when (apparently) absolutely necessary, and things start to get real whacked out. Finally, there's the issue of source code control. We use Visual SourceSafe, and most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. How absolutely stupid is that? What's funny is that we all agree that it needs to be fixed, but upper management would just laugh us out of the office if we suggested that we take the time to do so at our own expense (without having a "customer" to pay the bill). The effort would probably require the better part of a year (or more) just because we no longer have the original authors availble to us, and we lack the documentation that describes the architecture. Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation. "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
"Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation." That's only true, if the documentation is still up to date. If it's not, then I prefer no documentation over misleading documentation. I am a signature virus! Help me spread and copy me to your sig! Ooops I am infected
-
I am slowily learning this lesson, Last 3 title I have read are
- Debugging Applications
- Writing Solid Code
- Code Complete
Regards Ray "Je Suis Mort De Rire"
I am re-reading Mythical Man Month which was written some time in the early seventies. In it Brooks describes to a tee all of the mistakes that are still being made on project after project. It is kind of sad that we do not seem to learn. :(( PS There is a great page talking about clients complaining that the whole operating system takes up too much space -- at ~450KB :omg: But then he also states that rental of memory from IBM (Inefficient But Marketable) costs $12/month/Kilobyte!! :omg: :omg: :omg: Dave Huff There are no small projects - only young ones.
-
This is part of a reply I posted in the VC++ forum, but I figure it's something all of you might want to read and heed: ------------------------------------- There are aspects of this code that are INFURIATING, but the legacy is over seven years old. Like any other project I've been involved with over the last 15 years, nobody wants to pony up the bucks to make the code more maintainable by programmers that are new to the team. There's an almost complete lack of real technical documentation, and most of the guys that wrote the original code are LONG gone. Of course, in-source comments are non-existant in the most critical parts of the code, so the only vehicle we have is to review the source code one line at a time. I'm apprehensive about rebuilding the code unless we start from scratch because nobody is absolutely sure (and more often than not, not even remotely knowledgable) about how all the code interacts. It doesn't help when the code exhibits an eclectic coding style and non-adherance to anything that could be called corporate policy about how to write/format the code. Add to that an insane lack of use of MFC except when (apparently) absolutely necessary, and things start to get real whacked out. Finally, there's the issue of source code control. We use Visual SourceSafe, and most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. How absolutely stupid is that? What's funny is that we all agree that it needs to be fixed, but upper management would just laugh us out of the office if we suggested that we take the time to do so at our own expense (without having a "customer" to pay the bill). The effort would probably require the better part of a year (or more) just because we no longer have the original authors availble to us, and we lack the documentation that describes the architecture. Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation. "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
John Simmons / outlaw programmer wrote: most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. the last place i worked didn't even label their builds in VSS. the only way to reconstruct an old build was to grab a CD, check the dates on the files then grab the files in VSS that were checked in at the time the CD files were made. you often had to guess as to which revisions made the build and which didn't. they also had a total lack of Process for releases. their release process was: One sunny day, the product manager decides "we shall ship next thursday". development freaks out to try to tie up whatever they were working on. next thursday comes, we build, give the EXEs to the design team for a quick informal testing (no QA dept.). they find a bunch of bugs (all showstoppers, of course). we fix a bunch of bugs, test again, fix more bugs. late thursday comes, so we SHIP. friday AM, they test again, find more bugs, which we fix. so we ship again. this goes on through the middle of the next week. at the same time, the code was a mess, and only one of the original developers was still there. development management couldn't say no to design, which meant a constant stream of must-have new features to be added to a code base that was only partially understood by part of the team; design was totally informal: no specs, no reviews, no authority to say No. customers got fed up with our lack of rigorous testing, word got out about the lack of quality and sales stopped. -c
Smaller Animals Software, Inc. Few things are harder to put up with than the annoyance of a good example. Mark Twain
-
"Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation." That's only true, if the documentation is still up to date. If it's not, then I prefer no documentation over misleading documentation. I am a signature virus! Help me spread and copy me to your sig! Ooops I am infected
Even outdated documentation is better than NO documentation. At least we could see where they WANTED to go with the code (versus where they wound up). I think that when a class or function is written, it should be FILTHY with comments, including as lengthy of a discussion as is necessary that talks about why the class/function exists in the first place. I like to mark changes (even though we have the all-knowing source control app) with what was changed, by who, and why, because it makes the code easier to review later. My current boss thinks it's not necessary so I don't do it (for the sake of code format compatibility). "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
-
This is part of a reply I posted in the VC++ forum, but I figure it's something all of you might want to read and heed: ------------------------------------- There are aspects of this code that are INFURIATING, but the legacy is over seven years old. Like any other project I've been involved with over the last 15 years, nobody wants to pony up the bucks to make the code more maintainable by programmers that are new to the team. There's an almost complete lack of real technical documentation, and most of the guys that wrote the original code are LONG gone. Of course, in-source comments are non-existant in the most critical parts of the code, so the only vehicle we have is to review the source code one line at a time. I'm apprehensive about rebuilding the code unless we start from scratch because nobody is absolutely sure (and more often than not, not even remotely knowledgable) about how all the code interacts. It doesn't help when the code exhibits an eclectic coding style and non-adherance to anything that could be called corporate policy about how to write/format the code. Add to that an insane lack of use of MFC except when (apparently) absolutely necessary, and things start to get real whacked out. Finally, there's the issue of source code control. We use Visual SourceSafe, and most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. How absolutely stupid is that? What's funny is that we all agree that it needs to be fixed, but upper management would just laugh us out of the office if we suggested that we take the time to do so at our own expense (without having a "customer" to pay the bill). The effort would probably require the better part of a year (or more) just because we no longer have the original authors availble to us, and we lack the documentation that describes the architecture. Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation. "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
Comment heavilly and comment hard. I probably spend as much time commenting my code as I do writing it, if not more. I comment why things are done in a particular way, and sometimes more importantly why they aren't done in some other way, so down the track I don't waist time revisiting areas which I've previously decided won't work if done in a certain way. I work with a large complex project (ED4W)and this is pretty much all I do and have been doing for a long time. Without thorough comments I'd be lost and may as well close my business down. I find the amount of source code out there without even the simplist of comments quite mind boggling. And don't try and tell me that that reading the code is all you need - bollocks.:confused: Ok I'm done.;) Neville Franks, Author of ED for Windows. www.getsoft.com
-
I am re-reading Mythical Man Month which was written some time in the early seventies. In it Brooks describes to a tee all of the mistakes that are still being made on project after project. It is kind of sad that we do not seem to learn. :(( PS There is a great page talking about clients complaining that the whole operating system takes up too much space -- at ~450KB :omg: But then he also states that rental of memory from IBM (Inefficient But Marketable) costs $12/month/Kilobyte!! :omg: :omg: :omg: Dave Huff There are no small projects - only young ones.
Yeah, alot of the books refrence that one. I must read it at some stage, I think I will take one or two MCP's first though. Regards Ray "Je Suis Mort De Rire"
-
Even outdated documentation is better than NO documentation. At least we could see where they WANTED to go with the code (versus where they wound up). I think that when a class or function is written, it should be FILTHY with comments, including as lengthy of a discussion as is necessary that talks about why the class/function exists in the first place. I like to mark changes (even though we have the all-knowing source control app) with what was changed, by who, and why, because it makes the code easier to review later. My current boss thinks it's not necessary so I don't do it (for the sake of code format compatibility). "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
John Simmons / outlaw programmer wrote: I think that when a class or function is written, it should be FILTHY with comments, including as lengthy of a discussion as is necessary that talks about why the class/function exists in the first place. I like to mark changes (even though we have the all-knowing source control app) with what was changed, by who, and why, because it makes the code easier to review later. My current boss thinks it's not necessary so I don't do it (for the sake of code format compatibility). I think comments saying WHY are the most important of all of those. If code is written at least reasonably well, you can often tell *what* it is doing. But figuring out why it is doing something - or why a particular function is needed at all - requires commnents or some form of documentation. Moderately useful... length = 31; // Set the max length to 31 chars Extremely helpful... length = 31; // xxx.DLL will crash if the length is over 31 Winning isn't everything, but then, losing is nothing.
-
This is part of a reply I posted in the VC++ forum, but I figure it's something all of you might want to read and heed: ------------------------------------- There are aspects of this code that are INFURIATING, but the legacy is over seven years old. Like any other project I've been involved with over the last 15 years, nobody wants to pony up the bucks to make the code more maintainable by programmers that are new to the team. There's an almost complete lack of real technical documentation, and most of the guys that wrote the original code are LONG gone. Of course, in-source comments are non-existant in the most critical parts of the code, so the only vehicle we have is to review the source code one line at a time. I'm apprehensive about rebuilding the code unless we start from scratch because nobody is absolutely sure (and more often than not, not even remotely knowledgable) about how all the code interacts. It doesn't help when the code exhibits an eclectic coding style and non-adherance to anything that could be called corporate policy about how to write/format the code. Add to that an insane lack of use of MFC except when (apparently) absolutely necessary, and things start to get real whacked out. Finally, there's the issue of source code control. We use Visual SourceSafe, and most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. How absolutely stupid is that? What's funny is that we all agree that it needs to be fixed, but upper management would just laugh us out of the office if we suggested that we take the time to do so at our own expense (without having a "customer" to pay the bill). The effort would probably require the better part of a year (or more) just because we no longer have the original authors availble to us, and we lack the documentation that describes the architecture. Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation. "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
What's even worst than no comments? How about totally non-descriptive variable names. At one of my old jobs, there were some senior programmers who were very good at knowing how the code should work, but they were from the "old school" of programming - where variable names were as short as possible and no comments. (I think this was done to conserve memory space.) Which means you were left in a position where you were saying, "Gee, I can't really re-write it because I don't understand the system as well as they did, but why did they have to use 1 and 2 character variable names for everything?"
-
John Simmons / outlaw programmer wrote: most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. the last place i worked didn't even label their builds in VSS. the only way to reconstruct an old build was to grab a CD, check the dates on the files then grab the files in VSS that were checked in at the time the CD files were made. you often had to guess as to which revisions made the build and which didn't. they also had a total lack of Process for releases. their release process was: One sunny day, the product manager decides "we shall ship next thursday". development freaks out to try to tie up whatever they were working on. next thursday comes, we build, give the EXEs to the design team for a quick informal testing (no QA dept.). they find a bunch of bugs (all showstoppers, of course). we fix a bunch of bugs, test again, fix more bugs. late thursday comes, so we SHIP. friday AM, they test again, find more bugs, which we fix. so we ship again. this goes on through the middle of the next week. at the same time, the code was a mess, and only one of the original developers was still there. development management couldn't say no to design, which meant a constant stream of must-have new features to be added to a code base that was only partially understood by part of the team; design was totally informal: no specs, no reviews, no authority to say No. customers got fed up with our lack of rigorous testing, word got out about the lack of quality and sales stopped. -c
Smaller Animals Software, Inc. Few things are harder to put up with than the annoyance of a good example. Mark Twain
<irony> Chris I don't remember you as a coworker! And I really think you shouldn't discuss our internal problems in public! Shame on you! ;P:omg: ;P </irony>
Eddie Velasquez: A Squeezed Devil (Don't you just love that anagram craze?)
Checkout GUIDGen.NET -
What's even worst than no comments? How about totally non-descriptive variable names. At one of my old jobs, there were some senior programmers who were very good at knowing how the code should work, but they were from the "old school" of programming - where variable names were as short as possible and no comments. (I think this was done to conserve memory space.) Which means you were left in a position where you were saying, "Gee, I can't really re-write it because I don't understand the system as well as they did, but why did they have to use 1 and 2 character variable names for everything?"
-
Yeah, alot of the books refrence that one. I must read it at some stage, I think I will take one or two MCP's first though. Regards Ray "Je Suis Mort De Rire"
Read it, you won't regret it. After reading ~50 books covering similar area, i think it's the best book on software development ever written, although it's almost 30 years old. Few more suggestions: "The psychology of computer programming", G. Weinberg "Peopleware", DeMarco, Lister
-
John Simmons / outlaw programmer wrote: most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. the last place i worked didn't even label their builds in VSS. the only way to reconstruct an old build was to grab a CD, check the dates on the files then grab the files in VSS that were checked in at the time the CD files were made. you often had to guess as to which revisions made the build and which didn't. they also had a total lack of Process for releases. their release process was: One sunny day, the product manager decides "we shall ship next thursday". development freaks out to try to tie up whatever they were working on. next thursday comes, we build, give the EXEs to the design team for a quick informal testing (no QA dept.). they find a bunch of bugs (all showstoppers, of course). we fix a bunch of bugs, test again, fix more bugs. late thursday comes, so we SHIP. friday AM, they test again, find more bugs, which we fix. so we ship again. this goes on through the middle of the next week. at the same time, the code was a mess, and only one of the original developers was still there. development management couldn't say no to design, which meant a constant stream of must-have new features to be added to a code base that was only partially understood by part of the team; design was totally informal: no specs, no reviews, no authority to say No. customers got fed up with our lack of rigorous testing, word got out about the lack of quality and sales stopped. -c
Smaller Animals Software, Inc. Few things are harder to put up with than the annoyance of a good example. Mark Twain
...One sunny day, the product manager decides "we shall ship next thursday". development freaks out to try to tie up whatever they were working on. next thursday comes, we build, give the EXEs to the design team for a quick informal testing (no QA dept.). they find a bunch of bugs (all showstoppers, of course). we fix a bunch of bugs, test again, fix more bugs. late thursday comes, so we SHIP. friday AM, they test again, find more bugs, which we fix. so we ship again. this goes on through the middle of the next week.... I know! - and we have the audacity to call ourselves "engineers"! ... Can you imagine what the world would be like if "real" engineers built bridges, aircraft, freeways, etc. like that. :omg: We wouldn't dare go outside the house (unless our houses were built by "engineers" then we'd just have to go sit on the grass;) ) Steve T.
-
What's even worst than no comments? How about totally non-descriptive variable names. At one of my old jobs, there were some senior programmers who were very good at knowing how the code should work, but they were from the "old school" of programming - where variable names were as short as possible and no comments. (I think this was done to conserve memory space.) Which means you were left in a position where you were saying, "Gee, I can't really re-write it because I don't understand the system as well as they did, but why did they have to use 1 and 2 character variable names for everything?"
...How about totally non-descriptive variable names. ... Tell me about it! One of my old bosses (from whom I inherited a lot of code to work on) was a quadraplegic - had the use of one finger. - Brilliant coder but ALWAYS used 1 and 2 character variable names - and, since the shift key was difficult for him, lower case only. And of course not a single comment anywhere.:(( Steve T
-
This is part of a reply I posted in the VC++ forum, but I figure it's something all of you might want to read and heed: ------------------------------------- There are aspects of this code that are INFURIATING, but the legacy is over seven years old. Like any other project I've been involved with over the last 15 years, nobody wants to pony up the bucks to make the code more maintainable by programmers that are new to the team. There's an almost complete lack of real technical documentation, and most of the guys that wrote the original code are LONG gone. Of course, in-source comments are non-existant in the most critical parts of the code, so the only vehicle we have is to review the source code one line at a time. I'm apprehensive about rebuilding the code unless we start from scratch because nobody is absolutely sure (and more often than not, not even remotely knowledgable) about how all the code interacts. It doesn't help when the code exhibits an eclectic coding style and non-adherance to anything that could be called corporate policy about how to write/format the code. Add to that an insane lack of use of MFC except when (apparently) absolutely necessary, and things start to get real whacked out. Finally, there's the issue of source code control. We use Visual SourceSafe, and most of the source files are linked between major revisions of the code, so changing version 2.0 will also effect changes version 1.0. How absolutely stupid is that? What's funny is that we all agree that it needs to be fixed, but upper management would just laugh us out of the office if we suggested that we take the time to do so at our own expense (without having a "customer" to pay the bill). The effort would probably require the better part of a year (or more) just because we no longer have the original authors availble to us, and we lack the documentation that describes the architecture. Let this be a lesson to everyone else - you can NEVER have too much design and implementation documentation. "...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001
As much as I agree that comments are essential they aren't going to fix a codebase of spaghetti. Todd Smith CPUA 0x007 ... shaken not stirred
