Stop me if you've heard this before... [modified]
-
led mike wrote:
How do you document a methods pre and post conditions in a requirements document written "before" the method exists?
Okay, I could sit here and answer all these questions all day long ... or you could just go read this and save me a lot of typing ;P
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
-
led mike wrote:
- Why it is needed 2) Why the path or technique was selected 3) Why other path(s) were not selected. 4) Pre-conditions 5) Post-conditions 6) Exceptions that may be thrown
All that should be in the requirements documents. That is, written before coding has been started (granted, prototypes may have been written, but no production code yet).
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
Yes some of this should be in a good requirements document, yet I still believe you are confusing requirements documentation and code documentation. As the code migrates toward completion do you update the requirements docs also?
only two letters away from being an asset
-
I have that book for years. No where in it does it show how to document something that does not exist. ;P
led mike
Correct, it tells you how to document it BEFORE it exists so that you don't waste your time writing something that doesn't need to be written. Included in that documentation is use case analysis and high level design documents that go over the intentions for features and modules. Now, after all that, if you really need a document to explain a return value for a function who's name should be self explanatory to begin with ...
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
-
Yes some of this should be in a good requirements document, yet I still believe you are confusing requirements documentation and code documentation. As the code migrates toward completion do you update the requirements docs also?
only two letters away from being an asset
Mark Nischalke wrote:
As the code migrates toward completion do you update the requirements docs also?
Yes. Generally, the updates will discuss changes in design which were required based on problems encountered during implementation (which, if you spent enough time in the design documentation phase, should be minimal). It also would discuss why some features were either rejected completely, or were pushed to later iterations of the project. The important part to note here is that the original documents are kept in tact and only notes added to it explaining why things were done differently than designed.
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
-
Mark Nischalke wrote:
They looked at them then said, that's nice but we don't have the time to do it
I'm about to redesign (oh, excuse me, refactor--the word is so heavily abused) one class (out of hundreds), and I predict eliminating about 60-70% of the code. Code that should never have been written in an architecture that was hacked together instead of designed. And this is supposed to be more productive? Riiight. Marc
People are just notoriously impossible. --DavidCrow
There's NO excuse for not commenting your code. -- John Simmons / outlaw programmer
People who say that they will refactor their code later to make it "good" don't understand refactoring, nor the art and craft of programming. -- Josh SmithProductive for who? As a consultant it would be, and has been, productive for me to get paid to rewrite poorly written applications ;P
only two letters away from being an asset
-
Mark Nischalke wrote:
As the code migrates toward completion do you update the requirements docs also?
Yes. Generally, the updates will discuss changes in design which were required based on problems encountered during implementation (which, if you spent enough time in the design documentation phase, should be minimal). It also would discuss why some features were either rejected completely, or were pushed to later iterations of the project. The important part to note here is that the original documents are kept in tact and only notes added to it explaining why things were done differently than designed.
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
Wow, I hope to reach such a state of Nirvana some day.
only two letters away from being an asset
-
Mark Nischalke wrote:
Requirements documentation is vastly different from code documentation.
We will have to agree to disagree on this then.
Mark Nischalke wrote:
I would highly disagree with this point. Readable, self-documenting code does not take the place of well documented code.
The problem with documenting your code (as you are describing it) is that it creates a maintenence nightmare. Each and every revision must make sure that the code documentation is updated to match any changes in the code. I don't think we disagree on the need for documentation ... I just disagree with when it is done (and the scope of requirements documents apparently).
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
Zac Howland wrote:
Each and every revision must make sure that the code documentation is updated to match any changes in the code.
correct. And this is exactly why you WANT code documentation. If you change the code, and you changed the functionality, you change the documentation, because the intended use of that function/operation/method has changed. If you do not, your other 5 to 500 programmers have no idea you changed the intent, and they are still using the function as you intended it to be used 10 versions ago. changing the documentation doesn't solve keeping the other programmers up to date, but it sure lets them know when a bug pops up where to look. Oh hey, I used this Geodetic ASCII to double routine and used to output degrees, someone changed the bloody thing to Radians... oh hey it was my boss, I guess I better fix my code rather than ask him to change it back... ;)
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Sreenath Madyastha wrote:
if you are writing business centric application and the business rules keep changing
Set a baseline for the rules you will implement and implement them. If you keep trying to chase a moving target, your project will fail. If they want more rules to be implemented, tell them to submit it for the next revision of the product. The one thing that many developers don't learn is the ability to say "No", and "Not now". If you give in to managers/customers who change requirements on a whim, you never get anything shipped and end up losing lots of money. For more thorough explanations of this, read "Software Requirements" (I can't remember the author's name, but it is a Microsoft Press book).
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
Zac Howland wrote:
If you keep trying to chase a moving target,
It is called agile development. And there are cases where it is required. The target is always moving because technology is always moving. You use cyclic development and impliment rule sets with validation period of current and previous before moving on to new changes/additions. I shall not be asking my customer to stop building new equipment just so I can never chase a moving target. And I think you would rather my customer keep building the equipment. :)
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Zac Howland wrote:
If you keep trying to chase a moving target,
It is called agile development. And there are cases where it is required. The target is always moving because technology is always moving. You use cyclic development and impliment rule sets with validation period of current and previous before moving on to new changes/additions. I shall not be asking my customer to stop building new equipment just so I can never chase a moving target. And I think you would rather my customer keep building the equipment. :)
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
Agile Development has nothing to do with chasing a moving target. It has everything to do with approaching a product in iterations and breaking down a project into small parts that are easy to define. And yes, you want products to keep being built, but you must have an target platform to aim for. If you keep aimig for the latest and greatest stuff, you never ship a product and managers sit there wondering why you are eating up so much time and money.
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
-
Productive for who? As a consultant it would be, and has been, productive for me to get paid to rewrite poorly written applications ;P
only two letters away from being an asset
Mark Nischalke wrote:
As a consultant it would be, and has been, productive for me to get paid to rewrite poorly written applications
True. But I meant productive for the client. :) Marc
People are just notoriously impossible. --DavidCrow
There's NO excuse for not commenting your code. -- John Simmons / outlaw programmer
People who say that they will refactor their code later to make it "good" don't understand refactoring, nor the art and craft of programming. -- Josh Smith -
We need to improve our productivity. We don't have the time to look through the code to figure out what it is supposed to do. Do you document your code? No, the manager won't give us the time to do it. Then make time to do it. But I'll be less productive. And how is spending time looking through the code making you more productive? -- modified at 15:12 Wednesday 20th September, 2006 The above is a dialog with a client's developers (in italics) and me. Just to clarify So what are your views? I know we have deadlines and such but I subscribe to the belief that there is no excuse for not documenting your code, even if "my manager won't give me time to do it". Not writing a novel, but at least something.
only two letters away from being an asset
I've always thoroughly documented every bit of code I've ever written, even scripts for personal use on my personal computer here at home. I've always been like that since my punch-card days. No, I'm not anal-retentive or anything, it's just that I don't want to have to scratch my head, especially for compiler/script-bug workarounds that I forgot I did. There are always bugs, well except in my work. Two stories illustrate my point.
When I took a formal class on C, which I had been programming for nigh on six years, the final project was to create a flexible database system. In the rush to commit it to floppy, test it against a real live PC (I did all my work on mi Amigas), I kind of forgot something. The manual. The instructor took off one whole point out of one hundred since not only did the code document itself thoroughly, the on-screen prompts and help handheld the total novice painlessly through the whole process of definition and use.
Second story. My last project for the US Navy was to develop a supply (logistics) system that maintained the electronic equivalent of our paper-based logs. It was also to have the capability to project into the future anticipated budget requirements which is actually easier than it sounds when you get down to it. Anyway, I wrote the whole thing in dBase IV and wrapped it up. That week came the notice, delivered on Thursday no less, that I was to be medically put out to pasture on Friday. Gotta love the service. Anyway, as I was doing my final checkout, two total dBase IV, but not programming, novices were busily adding a supply form print feature to the code and doing a bang-up job of it. They were doing the final adjustments on form element placement as the door hit me in the behind. They had two copies of the code and that's all they needed.
Your job is not sacred and not commenting won't insure your job. Besides, have you ever looked at your undocumented code six months down the road and wondered "what was I thinking?". Just my $0.02
-Bri "The most deadly words for an engineer. 'I have an idea.'"
-
Wow, I hope to reach such a state of Nirvana some day.
only two letters away from being an asset
Then I've been in Nirvana a hell of a long time, some thirty plus years at last count and I'm only (just) fourty-six. I thought every software engineer worked that way. Engineering involves creating plans, taking those plans and turning them into completed projects, and documenting along the way deviations from the plans. I don't give a fig which field of engineering you are talking about. I've worked professionally in seven full engineering disciplines, often simultaneously, and bitten off pieces of several more, some of them quite abtruse.
I hate to be harsh, but if you want a code jockey, go look for someone else.
-Bri "The most deadly words for an engineer. 'I have an idea.'"
-
Correct, it tells you how to document it BEFORE it exists so that you don't waste your time writing something that doesn't need to be written. Included in that documentation is use case analysis and high level design documents that go over the intentions for features and modules. Now, after all that, if you really need a document to explain a return value for a function who's name should be self explanatory to begin with ...
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
Zac Howland wrote:
Included in that documentation is use case analysis and high level design documents that go over the intentions for features and modules.
Use case Analysis will NOT depict every method that will be written in the code. I could go on with an explanation of Use Cases or you could just read this[^] :-D Sorry couldn't resist.
led mike
-
Zac Howland wrote:
Included in that documentation is use case analysis and high level design documents that go over the intentions for features and modules.
Use case Analysis will NOT depict every method that will be written in the code. I could go on with an explanation of Use Cases or you could just read this[^] :-D Sorry couldn't resist.
led mike
led mike wrote:
Use case Analysis will NOT depict every method that will be written in the code.
I don't believe I ever said it would. I said (and you quoted) "intentions for features and modules". If you really need EVERY method documented to understand what it does, your code isn't being written in a readable manner. If you follow proper guidelines for writing functions, they will have a single objective and will be short enough that even a novice programmer would be able to look at it and have a good idea of what is going on.
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
-
led mike wrote:
Use case Analysis will NOT depict every method that will be written in the code.
I don't believe I ever said it would. I said (and you quoted) "intentions for features and modules". If you really need EVERY method documented to understand what it does, your code isn't being written in a readable manner. If you follow proper guidelines for writing functions, they will have a single objective and will be short enough that even a novice programmer would be able to look at it and have a good idea of what is going on.
If you decide to become a software engineer, you are signing up to have a 1/2" piece of silicon tell you exactly how stupid you really are for 8 hours a day, 5 days a week Zac
Zac Howland wrote:
your code isn't being written in a readable manner.
Now we have circled back to the original discussion about self-documenting code through names will NOT depict aspects like pre-conditions etc.
Zac Howland wrote:
If you follow proper guidelines for writing functions, they will have a single objective and will be short enough that even a novice programmer would be able to look at it and have a good idea of what is going on.
Sorry, but I disagree. Someone may understand that
int x = input << 5;will shift the value of "input" 5 bits left and store it in "x" but they will have no idea "why" the system needed to do that. This type of situation is fundamental in software development. I can't even believe I am having an argument about it.led mike
-
Zac Howland wrote:
your code isn't being written in a readable manner.
Now we have circled back to the original discussion about self-documenting code through names will NOT depict aspects like pre-conditions etc.
Zac Howland wrote:
If you follow proper guidelines for writing functions, they will have a single objective and will be short enough that even a novice programmer would be able to look at it and have a good idea of what is going on.
Sorry, but I disagree. Someone may understand that
int x = input << 5;will shift the value of "input" 5 bits left and store it in "x" but they will have no idea "why" the system needed to do that. This type of situation is fundamental in software development. I can't even believe I am having an argument about it.led mike
led mike wrote:
Now we have circled back to the original discussion about self-documenting code through names will NOT depict aspects like pre-conditions etc.
:sigh: I'm not even going to get back into that discussion again ...
led mike wrote:
Sorry, but I disagree. Someone may understand that int x = input << 5; will shift the value of "input" 5 bits left and store it in "x" but they will have no idea "why" the system needed to do that. This type of situation is fundamental in software development. I can't even believe I am having an argument about it.
Out of the context of the function, that line means nothing. However, if you had a function (simple silly example):
int multiply_by_32(int input) { return input << 5; }It should be clear. About the only thing you might want to comment there is why you used bitshifts instead of multiplying, but if it is in an area of code that needs to be highly optimized, that should also be self-explanatory (and should be mentioned at the top of the source file). Perhaps I should clarify why I disagree with documenting code too much after it has been written so you get an understanding of why it is a pain:
// Complex.h class Complex { public: // public members Complex(); // constructs Complex Complex(const Complex& c); // copy-constructs Complex ~Complex(); // destructs Complex Complex& operator= (const Complex& c); // copy-assigns Complex /* I declared the following functions as friends so that implicit casting can be used on the left side. I found out that if you make them member functions, only the right side of the operator can be implicitly casted. */ friend Complex operator+ (const Complex& l, const Complex& r); // adds 2 Complex numbers friend Complex operator- (const Complex& l, const Complex& r); // subtracts 2 Complex numbers friend Complex operator* (const Complex& l, const Complex& r); // multiplies 2 Complex numbers private: // private members double _real; // stores real part of number double _imaginary; // stores imaginary part of number }; /****************************************************\ * Adds 2 Complex numbers * Input: 2 valid complex numbers * Returns: valid complex number \****************************************************/ Complex operator+ (const Complex& l, const Complex& r) { Complex ret;