Just classes/functions/difficult algorithms should be commented. Everything else should be written to be innately descriptive/easy to read.
because its costs time to write documentation? and time == money?
and nevermind the problem to maintain the doc, esp when the code gets re-factored or updated... now u gotta update the code and doc.. and traces of the documentation could be everywhere... costing even more time and thus more money.
and if you write good code there is no need to write good documentation -- good code itself is the documentation.
I'd never hire anyone with your pathetic attitude. You think you'll save time and/or money on the front end, but you won't be able to retrace your steps to see how badly you screwed the pooch when your mistakes come to light, probably at the expense of many of your soon to be ex-clients. :thumbsdown:
Stay away from designing hardware or software, and stick with lower level management. Better yet, look for work in the shipping department or the cafeteria. 🙄
Having a bad day?Obviously, you never studied engineering, at least on the level of those who expect to make a living at it. Are you one of the idiots who wrote Milenium and Vista? 😱
I'd never hire anyone with your pathetic attitude. You think failing to document your work will save time and/or money on the front end, but you won't be able to retrace your steps to see how badly you screwed the pooch when your mistakes come to light, probably at the expense of many of your soon to be ex-clients. :thumbsdown:
Stay away from designing hardware or software, and stick with lower level management. Better yet, look for work in the shipping department or the cafeteria. 🙄
I'd never hire anyone with your pathetic attitude. You think you'll save time and/or money on the front end, but you won't be able to retrace your steps to see how badly you screwed the pooch when your mistakes come to light, probably at the expense of many of your soon to be ex-clients. :thumbsdown:
You obviously never studied engineering, engineering is about analysis and making trade-off decisions. Op asked for reasons why he wouldn't write documentation. I gave him that.
There are situations where documentation (and good documentation) is necessary, but there are others where they are not. Because the time and cost associated with it just isn't worth it. This is what engineering is about, when to decide to write documentation, and when it is not worth my time.
Plus, I still stand by if you can write good code, there is no need to explain your code. Granted if you're able to write good code...
Stay away from designing hardware or software, and stick with lower level management. Better yet, look for work in the shipping department or the cafeteria. 🙄
🙄 If you're so rigid that you need to follow the book for everything-- (i.e. need to write documentation for all code, maybe you should stick to working as the guy that brings me coffee.. 🙄
Then, you'd better explain that to the audio equipmant company where I was chief engineer, and you'll really have to explain to me how I wrote the application and did the drawings for my own second patent and had it accepted by USPTO.
... blah blah blah .....
Ya know, that isn't my problem. I work for my own company, and I'm too particular about my coffee to trust making it to anyone who doesn't understand why documenting your work is important or a slacker who's too lazy to do it. 😎
Then, you'd better explain that to the audio equipmant company where I was chief engineer, and you'll really have to explain to me how I wrote the application and did the drawings for my own second patent and had it accepted by USPTO.
The OP asked for reasons why he wouldn't write documentation. You gave him bullsh8 excuses. The only time they would apply is if YOU are going to be the only person who will ever have to deal with the code you're writing and service the end users for as long as it's used, and no one will ever have to depend on your work when you're not around.
< sarcasm >
And of course, you've always written flawless code that never had to be updated, even to deal with emerging conditions or to interface and/or work with other egomaniacs who thought their code was as flawless as yours.
< /sarcasm >
Ya know, that isn't my problem. I work for my own company, and I'm too particular about my coffee to trust making it to anyone who doesn't understand why documenting your work is important or a slacker who's too lazy to do it. 😎
I've written two patent applications, one accepted, one pending, both for software, a profession I have been practicing since 1987. So now that the epeens are on the table 🙂, let me say that I have problems with your reply.
The software design and development process has nothing like the risks, and thus nothing like the rigor, of the hardware process. The question of how best to document software is very much an open one, and admits all views as relevant.
Yes, even the view that the source should be clear and self-documenting, which I subscribe to in part.
Documentation remains a huge issue, and the question is nowhere near answered. In that light your reply to lambchop511 looks like an overreaction.
Your profession has like a hundred years head start on us.
Ummm, you haven't posted in this thread, unless you have two accounts...I never guaranteed anything -- Op asked for "I dont see any pro's to NOT document source code. Any help would be appreciated." and I gave him reasons.
Note: I also said: "There are situations where documentation (and good documentation) is necessary, but there are others where they are not." .. I never said "DONT USE DOCUMENTATION" ... but I also didn't say "USE DOCUMENTATION" ... I said engineering is about analysis, judgement and flexibility.
If YOUR project requires you to do documentation, because it is more economical (whether in long run or short run) to spend resources to write documentation, then so be it. It doesn't mean ALL projects should require documentation.
Ummm, you haven't posted in this thread, unless you have two accounts...
Sure-- but if Probability(Failure) * Cost(Failure) < Cost(Documentation) ... then documentation shouldn't be written. Its an engineering decision, not ALL projects require documentation. Note I'm not arguing documentation is bad-- but I am saying it isn't good for all cases.
The question is, you have limited resources Today.. what can I do to maximize profit (whether Today or Tomorrow).. Do I dedicate my resources into documentation? Or do I dedicate my resources into writing more code? Or do I dedicate my resources elsewhere?
Then, you'd better explain that to the audio equipmant company where I was chief engineer, and you'll really have to explain to me how I wrote the application and did the drawings for my own second patent and had it accepted by USPTO.
The OP asked for reasons why he wouldn't write documentation. You gave him bullsh8 excuses. The only time they would apply is if YOU are going to be the only person who will ever have to deal with the code you're writing and service the end users for as long as it's used, and no one will ever have to depend on your work when you're not around.
< sarcasm >
And of course, you're immortal and immune to everything short of red kryptonite, and you've always written flawless code that never had to be updated, even to deal with emerging conditions or to interface and/or work with other egomaniacs who thought their code was as flawless as yours.
< /sarcasm >
Ya know, that isn't my problem. I work for my own company, and I'm too particular about my coffee to trust making it to anyone who doesn't understand why documenting your work is important or a slacker who's too lazy to do it. 😎
My only point is that, in a commercial/professional environment, documentation is important because producing and releasing a commercial product without it is creating a failure mode and begging for it to happen. No company should release a product that relies on one person to be around forever without so much as a vacation or minor illness, let alone recall every line of code in software or every circuit and mechanical specification in hardware.
I know it takes time. I know it slows things down, and I know there are times when you have to work quickly and go back to annotate the work in stages, but there's never a time when you can simply skip it.
I agree, but how can lambchops511 guarantee that every software and hardware construct will meet that ideal?
Hardly. I've been hired to rescue far too many product designs where the first, large number of paid hours were spent reconstructing what was there, even before I could determine what the problem was.
There's no guarantee a product, software or hardware will fail, but there's no guarantee it won't. Good documentation is merely preparing for a worst case situation. How much is a company's reputation and market share worth when a product fails encounters a spectacular public failure in the hands of end users?
Of course, the same people always do it after the catastrophe. It gets down to the old saw about why nobody has time to do things right the first time, but they always have time to do it right the second time.
I prefer to do my second takes first. 😎
Imagine if NVIDIA released their GTX 460 6 months earlier, albeit without internal code documentation, or even with shitty drivers that crashed in certain games. Would they be in a different situation financially Today? How much more revenue would they have taken in from lost sales to ATI's 58XX/57XX chips? Sure, it'll hurt their reputation, but they can also release new drivers later...
Mmmmm, I want to rebut this, but you know what? It worked for Microsoft. And I don't mean to be flip. They understood the importance of getting and preserving mindshare above all else.
But... the philosophy of product development and release isn't really the point of this thread. I don't think documentation is the make/break cost issue for even small OEMs. It's fairly easy to produce end-user documentation, and the costs have been driven down tremendously. But I think if the thread is to have any further relevance you need to pick one kind of documentation and stick with it. End-user documentation is far different from engineering design and source documentation, which is where I thought we were a few posts back.
The question is, you have limited resources Today.. what can I do to maximize profit (whether Today or Tomorrow).. Do I dedicate my resources into documentation? Or do I dedicate my resources into writing more code? Or do I dedicate my resources elsewhere?
That's a sociological problem, not one related to good engineering practice. Putting "profit" ahead of safety or just good common sense is how BP gave us the Gulf oil spill.
Personally, if the situation demanded that I do less than my best work, including documentation, I'd decline the project. If they insisted, and I had the time, and the end product wasn't one where reliability was critical on the level of life or death or defense, I'd demand extra pay up front above my normal rate front with no guarantee of success and no liability for failure.
That isn't theory. I actually had a defense contractor client where I was the third engineer to take on a project that was late and horribly under-documented by the two guys who had failed, before me. They had spec sheets for only a few of many critical components, some of which they obviously didn't understand, and they didn't even have a block diagram showing all inputs and all routings to all outputs.
After spending a few days figuring out what they actually had, I realized that some of their circuits read like stand up comedy for circuit designers... except that, if they failed, American troops' lives could be on the line in a combat situation. 😱
I asked for a meeting with every person who had authority over the project. At the meeting, I told them we were going to develop the necessary block diagram, and I insisted that every one of them sign off on the diagram we developed that it was exactly what they wanted.
When they complained that my methodology would take too long, I told them I had enough info to write a report outlining what was needed, but if they wanted me to design it, I only knew one way to do it, my way, and it would take the time I spec'd. I also said that any competent designer would be able to work from my report, and if they thought they had someone who could do it faster, they should hire that person.
I don't willingly sign up for failure. :hmm:
That's a sociological problem, not one related to good engineering practice. Putting "profit" ahead of safety or just good common sense is how BP gave us the Gulf oil spill.
Personally, if the situation demanded that I do less than my best work, including documentation, I'd decline the project. If they insisted, and I had the time, and the end product wasn't one where reliability was critical on the level of life or death or defense, I'd demand extra pay up front above my normal rate front with no guarantee of success and no liability for failure.
That isn't theory. I actually had a defense contractor client where I was the third engineer to take on a project that was late and horribly under-documented by the two guys who had failed, before me. They had spec sheets for only a few of many critical components, some of which they obviously didn't understand, and they didn't even have a block diagram showing all inputs and all routings to all outputs.
After spending a few days figuring out what they actually had, I realized that some of their circuits read like stand up comedy for circuit designers... except that, if they failed, American troops' lives could be on the line in a combat situation. 😱
I asked for a meeting with every person who had authority over the project. At the meeting, I told them we were going to develop the necessary block diagram, and I insisted that every one of them sign off on the diagram we developed that it was exactly what they wanted.
When they complained that my methodology would take too long, I told them I had enough info to write a report outlining what was needed, but if they wanted me to design it, I only knew one way to do it, my way, and it would take the time I spec'd. I also said that any competent designer would be able to work from my report, and if they thought they had someone who could do it faster, they should hire that person.
And yes, they hired me to complete it, and it worked.
I don't willingly sign up for failure. :hmm:
That's a sociological problem, not one related to good engineering practice. Putting "profit" ahead of safety or just good common sense is how BP gave us the Gulf oil spill.
I am not an expert in Oil so I cannot comment. But I assume the engineers were confident that whatever they were doing would be successful (if they weren't confident, and still did whatever they were doing then they shouldn't be engineers). Sometimes nobody can predict mother nature...
BP's internal investigation of oil spill: Several 'warning signs' were ignored
By Steven Mufson
Washington Post Staff Writer
Wednesday, May 26, 2010
BP's internal investigation of the Gulf Coast oil spill points to a series of equipment failures, mistakes and missed warning signs that led to the blowout and fire on the Deepwater Horizon drilling rig, according to lawmakers briefed by the company.
BP's investigation, while incomplete, highlights a series of abnormal indicators -- about pipeline pressure and the flow of drilling fluids in the five hours before the explosion -- that should have been "warning signs" of trouble, according to a memo summarizing BP's report. In one case, BP's investigator told lawmakers that a "fundamental mistake may have been made despite" an indicator of a very large abnormality.
BP also said it had concerns about the cementing job in the well, saying that one procedure had to be attempted nine times, which might have indicated "contamination of the cement."
In addition, lawmakers said, "the BP investigation has also raised concerns about the maintenance history, modification, inspection, and testing of" the blowout preventer. The account of BP's investigation was contained in a House Energy and Commerce Committee memorandum.
Once the blowout began, all the systems in place to prevent disaster broke down in serial fashion, the memorandum said, "including the failure of its emergency disconnect system (EDS), the failure of its automated mode function or deadman switch, the failure of the [blowout preventer's] shearing functions, and the failure of the remote operated vehicle interventions."
Reports at BP over years find history of problems
By Abrahm Lustgarten and Ryan Knutson
Tuesday, June 8, 2010
ProPublica
A series of internal investigations over the past decade warned senior BP managers that the oil company repeatedly disregarded safety and environmental rules and risked a serious accident if it did not change its ways.
The confidential inquiries, which have not previously been made public, focused on a rash of problems at BP's Alaska oil-drilling operations. They described instances in which management flouted safety by neglecting aging equipment, pressured employees not to report problems and cut short or delayed inspections to reduce production costs.
Similar themes about BP operations elsewhere were sounded in interviews with former employees, in lawsuits and little-noticed state inquiries, and in e-mails obtained by ProPublica. Taken together, these documents portray a company that systemically ignored its own safety policies across its North American operations -- from Alaska to the Gulf of Mexico to California and Texas. Executives were not held accountable for the failures, and some were promoted despite them.
.
.
(continues)