- Site menu:
- Latest Discussions
- Latest Newswire
- Archives
- Submit Story
- Story HOWTO
- Syndicate
- E-mail Alerts
Linux Documentation Bug - A Programers Perspective
|
|
|
Comments (26)
6 earlier comments in the full thread.
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.
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.
Quoting:What do they teach in comp sci classes these days?
Visual Basic
"In short, programmers who do not properly document are cr@p programmers.
Period."
totally agree period end of story. nothing else to add.
totally agree period end of story. nothing else to add.
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 :)
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 :)
wow number6x, I'm glad your wife did not become an overnight millionaire!
6x -
Yeah, don't die. Unless you want to add me to your insurance.
In that case, I could always get some grief counseling.
Yeah, don't die. Unless you want to add me to your insurance.
In that case, I could always get some grief counseling.
Quoting:What do they teach in comp sci classes these days?
Visual Basic
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.
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.
Interactive COBOL on Windows? Thank $DEITY the nightmares are over.
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.
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.
>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.
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.
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
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
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.
But, but...
How do you put cleats on wooden shoes?
How do you put cleats on wooden shoes?
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.
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.
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.
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.
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.
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!
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!
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.
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.
Post a comment
A free account is needed to post. Write your comment here first: your text is kept in this browser while you sign up or log in, and is waiting for you when you come back.
Your message:Markdown: **bold**, *italic*, [text](https://link), - lists, > quotes, $x^2$ for math. Formatting help
Sign up and post (it is free) or Log in and post
"Dad, The yellow ones don't stop!"