Yes, that is it in a nutshel
|
| Author | Content |
|---|---|
| tracyanne Dec 22, 2009 3:40 AM EDT |
nt |
| dinotrac Dec 22, 2009 7:40 AM EDT |
Not s**t! What do they teach in comp sci classes these days? Back in the dark ages, I was taught that undocumented code might as well not exist. Working with free software (and that's nearly all I do) makes me appreciate the truth of that sentiment. |
| caitlyn Dec 22, 2009 11:16 AM EDT |
What I was taught back in the late '70s and early '80s is just what dino was taught: documentation is an essential part of the code. If G-d forbid the developer is hit by a bus tomorrow and is in the hospital somebody else has to be able to step in and continue the work. The ability to do that effectively is entirely based on good documentation. Also, what good is brilliant code if the potential user doesn't understand how to use it? Good documentation for the end user is equally essential. |
| number6x Dec 22, 2009 11:23 AM EDT |
It was a cab not a bus. Ron and Manoj both thanked me that I document my code well. I'm back at work now and still documenting. |
| caitlyn Dec 22, 2009 11:27 AM EDT |
I'm sorry you were hurt but glad you've recovered enough to be back at work. |
| dinotrac Dec 22, 2009 12:25 PM EDT |
It wouldn't be a bad thing to get back to that old truth. In short, programmers who do not properly document are cr@p programmers. Period. |
| number6x Dec 22, 2009 12:43 PM EDT |
My kids like to paraphrase the line from the holiday movie 'Elf'': "Dad, The yellow ones don't stop!" |
| dinotrac Dec 22, 2009 12:59 PM EDT |
6x - I have great respect for cabbies. They do a tough and dangerous job. Without them, urban centers would be a mess. But, it should be OK to hunt them down and kill them for failing to honor pedestrian right of way. Or, at the very least, to question their parentage. |
| techiem2 Dec 22, 2009 1:49 PM EDT |
Quoting:What do they teach in comp sci classes these days? Visual Basic |
| jsusanka Dec 22, 2009 2:08 PM EDT |
"In short, programmers who do not properly document are cr@p programmers.
Period." totally agree period end of story. nothing else to add. |
| number6x Dec 22, 2009 2:10 PM EDT |
I just kept showing up in traffic Court.
The cabbie's lawyer kept asking for continuances. Finally I showed up once and he didn't. He lost his cabbie license and got his driver's license suspended. That's a hunt (following up in Court) and a kill (of his license, so not to endanger others) in my book! My health insurance billed the cab company's insurer and got all bills reimbursed. Funny story though, I had one life insurance policy but after having a second child my wife and I decided to increase my life insurance. We went with another company. The morning of the accident I got a call that the new policy was in effect and I made a call to cancel the old policy, but it would still be in effect until the end of the month. I was insured for over $1 million, went for a walk at lunch and got hit by a cab. I ordered flowers for my wife with a card saying "sorry I didn't die". She always jokes that she'll pay the cabbie more next time :) |
| tuxchick Dec 22, 2009 2:15 PM EDT |
wow number6x, I'm glad your wife did not become an overnight millionaire! |
| dinotrac Dec 22, 2009 4:34 PM EDT |
6x - Yeah, don't die. Unless you want to add me to your insurance. In that case, I could always get some grief counseling. |
| tracyanne Dec 22, 2009 5:23 PM EDT |
Quoting:What do they teach in comp sci classes these days? It doesn't matter, as long as they teach good structured programming principles. A person who has been taught to design and write well structured self documenting code can learn any other language and port those skills to it. |
| gus3 Dec 22, 2009 7:22 PM EDT |
Conversely, any programming language can be abused into a write-only idiom. Even COBOL, which reads like English when handled well, can be turned into a tangled mess. Interactive COBOL on Windows? Thank $DEITY the nightmares are over. |
| tracyanne Dec 22, 2009 8:24 PM EDT |
Quoting:Even COBOL, which reads like English when handled well, can be turned into a tangled mess. I worked with a bloke who managed exactly that. He reckoned GOTO made his code faster. It also made it unreadable. |
| hkwint Dec 23, 2009 8:17 AM EDT |
Quoting:Without them, urban centers would be a mess. Guess you haven't been in Amsterdam the last two years! For those who don't understand: There was a "cab-war" going on between several companies, and it went so far one customer of some cab was hit with a baseball bat by some cab-driver. |
| dinotrac Dec 23, 2009 8:56 AM EDT |
>Amsterdam in the last ten years No, I haven't. Sigh. (Well, except for the getting hit by a baseball bat part.) Hmmmm. Raises a question, though. Amsterdam? Baseball bat? We seem to have a sport-location discontinuity here. |
| jacog Dec 23, 2009 8:57 AM EDT |
Cab war eh? Well, here in SA we have taxi wars, usually resulting in violence, assassinations etc. http://en.wikipedia.org/wiki/Taxi_wars_in_South_Africa http://news.bbc.co.uk/2/hi/africa/854000.stm |
| caitlyn Dec 23, 2009 12:03 PM EDT |
Quoting:Amsterdam? Baseball bat? We seem to have a sport-location discontinuity here. Tell that to the Dutch national team which upset (and ultimately eliminated) the Dominican Republic during the World Baseball Classic. There have been a handful of very talented Dutch players who went on to become major league baseball players in the U.S. Probably the most famous when I was growing up was Bert Blyleven. Kansas City Royals starter Sidney Ponson was the Dutch team's closer during the Classic. The Yankees signed the Dutch team's best hitter who finished the season at AAA for them. Oh, and yeah, my dad and brother were very into baseball. My brother's wife is an absolute fanatic when it comes to the Atlanta Braves. No avoiding baseball in my family. |
| dinotrac Dec 23, 2009 12:42 PM EDT |
But, but... How do you put cleats on wooden shoes? |
| hkwint Dec 23, 2009 5:22 PM EDT |
Quoting:There have been a handful of very talented Dutch players Actually, we cheated because 90% of them are from the Dutch Antilles - and a large part of them will belong to a different country after Oct '10 if I understand correctly (actually, almost nobody in the European part of our Kingdom cares). But anyway, back to documentation: -Where do you learn to write good documentation, if not in class? -Could you learn it 'online' for free? -What are the chances that anyone approaches a FOSS project and says: "I want to contribute docs, not code" to be accepted? These are the things I wonder. When people say: "You don't have to contribute code, you can contribute doc as well", I guess you can't contribute dev-doc unless you understand code. And to understand code, you have to be some sort of coder. And if you're some sort of coder, "they" will probably ask you to fix bugs instead of write docs. So then I guess it's "them" who need to change. |
| dinotrac Dec 23, 2009 5:31 PM EDT |
hans -- When you are doing a FLOSS project, you have a lot more power over your product than you do in the proprietary world. As to learning how to write documentation, I don't know that there is any one way that serves best -- especially when talking about code comments and API docs. A description of what you are doing ("Calculate standard deviation" , with some more detailed comments (get square root of sum of deviations squared) where the step may not be obvious, etc. Coders like to assume that the code itself is documentation, but that is lazy and stupid. The code documents what you wrote, but doesn't say anything about what you were trying to accomplish and why. The code you wrote might be the worst possible way to do what you want to do, but somebody else coming along later won't readily be able to know that. |
| tuxchick Dec 23, 2009 5:52 PM EDT |
What is all this silliness about "coders cannot possibly document their work, because first of all they suck at it, and secondly it's dumb and boring, and thirdly it means they will not get anything else done, and then the world will collapse." I hear this all the time, and to me it adds up to shoddy work and laziness. I personally have met hundreds of people in my life who can do more than one thing. Like put on and tie both shoes, drive a car and ride a bike, read a book and a newspaper, operate multiple kitchen appliances and power tools, and some have even walked and chewed gum at the same time. This weird ethos that claims programmers are fragile darlings who must not be distracted from their sacred programming, and never asked to do anything else, is a shuck and we shouldn't fall for it. Who is better-qualified to document code than the author? Is it really so unreasonable to expect a programmer to document everything their program does, all the commands and switches, the functions, and what-have-you? Expecting someone else to do it doesn't make sense. It's inefficient, because a second person has to get up to speed, and even a whizbang code reader needs time to get the hang of someone else's code. I wouldn't expect all coders to have the ability to churn out beautiful sleek end-user howtos that even Drunken Uncle Jake can follow. But for darn sure they can write out everything their sacred code does, or is supposed to do, and how to make it go. What kind of pretend helplessness tries to make that into an impossible task? It's absurd. When I hear all the excuses for not doing that, I suspect the code in question is probably not that good, and the author doesn't have a clear idea what it's for anyway. |
| tuxchick Dec 23, 2009 5:58 PM EDT |
Oh. And merry *%@!! christmas! I didn't mean to rant, but this is a prevalent attitude in FOSS, and it's stupid and needs to die die die. And then go away. As the article says: "the job ain’t finished until someone else can follow it without ‘reading the source’." Thank you! |
| dinotrac Dec 23, 2009 6:18 PM EDT |
TC - And a merry Christmas to you, too! Like you, I am really tired of pompous little morons who think they they're hot snot when really they're just snot. Documentation. Without it, you have cr@p. |
Posting in this forum is limited to members of the group: [ForumMods, SITEADMINS, MEMBERS.]
Becoming a member of LXer is easy and free. Join Us!