Stop me if you've heard this before... [modified]
-
That's a start but it may not indicate things like: 1) 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 ...... etc.
led mike
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
-
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
Zac Howland wrote:
All that should be in the requirements documents.
:wtf:
Zac Howland wrote:
That is, written before coding has been started
How do you document a methods pre and post conditions in a requirements document written "before" the method exists? :confused:
led mike
-
Jeffry J. Brickley wrote:
documentation documents intent
I expect my requirements documents to do that. I learned the hard way not to start coding a damn thing until you have completed the requirements gathering phase of development (which managers want to do least since it is generally where they are the ones doing most of the work). As developers, it is important to not let your manager/requirements analyst to skate by doing little to nothing while putting all the pressure/blame on you to implement crazy code. With proper requirements documents and readable code, there is no need to document code afterwards, and in fact, doing so would likely cause maintenence headaches later since the code is likely to be changed slightly and would require the documentation to be updated accordingly.
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:
I expect my requirements documents to do that.
Requirements documentation is vastly different from code documentation.
Zac Howland wrote:
With proper requirements documents and readable code, there is no need to document code afterwards
I would highly disagree with this point. Readable, self-documenting code does not take the place of well documented code.
only two letters away from being an asset
-
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
Mark Nischalke wrote:
But I'll be less productive.
I often hear the "but we need to get product out". And this applies to other aspects of programming too, not just documentation. Things like up front design, unit testing, etc.
Mark Nischalke wrote:
know we have deadlines and such but I subscribe to the belief that there is no excuse for not documenting your code
It is amazing beyond belief to me that anyone would not do at least minimal architecture and minimal documentation, regardless of time/money crunch realities. Because that minimal effort will SAVE YOU TIME. I'm preaching to the choir, I know. Unfortunately, the choir is not employeed by the majority of companies and clients I've worked for. 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 -
Sreenath Madyastha wrote:
This is because he will be not be having enough privelage or authority to go with it.
This is where you are wrong. If your manager keeps asking for unreasonable requirements (e.g. no documented requirements or constantly changing requirements), he is a poor manager. You can go about it several ways: talk to them about creating firm requirements for the project, talk to their boss about having firm requirements established (and possibly your boss' lack of desire for such), request a transfer to another division within your company, or simply find a new job. Firms that have too many managers that behave like this don't tend to stay in business long anyway.
Sreenath Madyastha wrote:
Performance / apprisal all depends on it. Manager has to think before involving with more engagement than wrapping up things. We tried to convince but manager is the boss!
This is when you need to suggest a requirements analyst be added to the team. Their job being to gather, document, and either accept or reject a set of requirements for each revision (and give a reason for rejection) of a product. Typically, managers try to do this, but if they are failing at it (either by choice or simply because of lack of knowledge), it is time to fix the process.
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
Where do you work at? I'd like to join this perfect world of yours :)
only two letters away from being an asset
-
Mark Nischalke wrote:
But I'll be less productive.
I often hear the "but we need to get product out". And this applies to other aspects of programming too, not just documentation. Things like up front design, unit testing, etc.
Mark Nischalke wrote:
know we have deadlines and such but I subscribe to the belief that there is no excuse for not documenting your code
It is amazing beyond belief to me that anyone would not do at least minimal architecture and minimal documentation, regardless of time/money crunch realities. Because that minimal effort will SAVE YOU TIME. I'm preaching to the choir, I know. Unfortunately, the choir is not employeed by the majority of companies and clients I've worked for. 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 SmithI know what you mean. I came to a meeting (at another client) armed with PowerPoint's and references showing the benefits of upfront design. They looked at them then said, that's nice but we don't have the time to do it :wtf::wtf::omg:
only two letters away from being an asset
-
Sreenath Madyastha wrote:
This is because he will be not be having enough privelage or authority to go with it.
This is where you are wrong. If your manager keeps asking for unreasonable requirements (e.g. no documented requirements or constantly changing requirements), he is a poor manager. You can go about it several ways: talk to them about creating firm requirements for the project, talk to their boss about having firm requirements established (and possibly your boss' lack of desire for such), request a transfer to another division within your company, or simply find a new job. Firms that have too many managers that behave like this don't tend to stay in business long anyway.
Sreenath Madyastha wrote:
Performance / apprisal all depends on it. Manager has to think before involving with more engagement than wrapping up things. We tried to convince but manager is the boss!
This is when you need to suggest a requirements analyst be added to the team. Their job being to gather, document, and either accept or reject a set of requirements for each revision (and give a reason for rejection) of a product. Typically, managers try to do this, but if they are failing at it (either by choice or simply because of lack of knowledge), it is time to fix the process.
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
-
Where do you work at? I'd like to join this perfect world of yours :)
only two letters away from being an asset
Its not perfect, but it is far better than where I was at before (like I said, I learned tha hard way that chasing moving targets ALWAYS leads to failed projects). But I work for a defense contract that does modeling and simulation work.
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:
Most large companies behave like that.
Yes, I'm well aware of the practices of places like EA, Microsoft, Oracle ... I'm also well aware of their turnover rate for both developers and middle managers. For those large corporations, yes, they stay in business, but if you look at your division as the "company", it won't if things are being done this way.
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:
All that should be in the requirements documents.
:wtf:
Zac Howland wrote:
That is, written before coding has been started
How do you document a methods pre and post conditions in a requirements document written "before" the method exists? :confused:
led mike
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
-
I know what you mean. I came to a meeting (at another client) armed with PowerPoint's and references showing the benefits of upfront design. They looked at them then said, that's nice but we don't have the time to do it :wtf::wtf::omg:
only two letters away from being an asset
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 Smith -
Zac Howland wrote:
I expect my requirements documents to do that.
Requirements documentation is vastly different from code documentation.
Zac Howland wrote:
With proper requirements documents and readable code, there is no need to document code afterwards
I would highly disagree with this point. Readable, self-documenting code does not take the place of well documented code.
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
-
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)