Stop me if you've heard this before... [modified]
-
I think the time to document should also be included when deadlines are being drawn. Documentation is always a good thing and it is not only for the next programmer or your PM. Why? Because of all the phases in the software development life cycle the maintenance phase is the biggest and if you don't document your own code how will you know what you were thinking when you wrote it?
-
Typically, I write my code specifically to be self-documenting. If I absolutely must do something that looks strange, I make sure to comment it well. Other than that, names for variables, functions, etc should make their purpose self-explanatory.
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:
Typically, I write my code specifically to be self-documenting. If I absolutely must do something that looks strange, I make sure to comment it well. Other than that, names for variables, functions, etc should make their purpose self-explanatory.
Theoretically, this is true. However, Documentation is different than self-explanatory code in that documentation documents intent, code is functionality. When intent and functionality match, generally you have at least bug-free code. When code is used against its intent, or intent and functionality do not match (unwanted side-effects, or just not quite doing what you wanted it to do), you have bugs. Although I am a firm supporter of self-explanatory code, I still want the documentation, if only to document intent. Debugging can be shortened significantly by comparing intent with functionality. Otherwise how do I know you didn't intend to share a global value that inhibits reentrant behavior?
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Typically, I write my code specifically to be self-documenting. If I absolutely must do something that looks strange, I make sure to comment it well. Other than that, names for variables, functions, etc should make their purpose self-explanatory.
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
Given an option, if you are writing business centric application and the business rules keep changing ( they keep changing till its deadline reached)? What we suppose to do then ?
-
Zac Howland wrote:
Typically, I write my code specifically to be self-documenting. If I absolutely must do something that looks strange, I make sure to comment it well. Other than that, names for variables, functions, etc should make their purpose self-explanatory.
Theoretically, this is true. However, Documentation is different than self-explanatory code in that documentation documents intent, code is functionality. When intent and functionality match, generally you have at least bug-free code. When code is used against its intent, or intent and functionality do not match (unwanted side-effects, or just not quite doing what you wanted it to do), you have bugs. Although I am a firm supporter of self-explanatory code, I still want the documentation, if only to document intent. Debugging can be shortened significantly by comparing intent with functionality. Otherwise how do I know you didn't intend to share a global value that inhibits reentrant behavior?
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
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
-
Given an option, if you are writing business centric application and the business rules keep changing ( they keep changing till its deadline reached)? What we suppose to do then ?
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
-
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'm curious why the developer(s) would need to make the distinction between coding and documenting. They should be one in the same. Asking a manager to do anything but produce "code" is just a recipe for a big no.
"Talent without discipline is like an octopus on roller skates. There's plenty of movement, but you never know if it's going to be forward, backwards, or sideways." - H. Jackson Brown, Jr.
"Judge not by the eye but by the heart." - Native American 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:
The one thing that many developers don't learn is the ability to say "No", and "Not now".
This is because he will be not be having enough privelage or authority to go with it.
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! -
Typically, I write my code specifically to be self-documenting. If I absolutely must do something that looks strange, I make sure to comment it well. Other than that, names for variables, functions, etc should make their purpose self-explanatory.
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:
The one thing that many developers don't learn is the ability to say "No", and "Not now".
This is because he will be not be having enough privelage or authority to go with it.
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!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
-
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