Your comments are written to answer questions that the people reading your code cannot readily answer for themselves.
Your procedure is:
Anticipate those questions.
Rewrite your code, completely, until as few questions as possible remain. If you skip this step, you're a poser hack.
Answer those questions.
Now go back and do it again, treating your comments as you did the code.
Eschew excess verbiage!
Eschew excess verbiage!
Eschew excess verbiage!
Needless words are a complete and utter waste of time. If you're stuck in some PHB-driven environment that insists your comments provide unneeded answers, find some way of marking what matters. Right-justify the real comments, whatever works.
Whitespace is a language. Find the arbitrary parts in whatever style you're matching and make your use of them mean something that helps readers. Indent variable definitions differently, to subtly highlight them. One blank line or two?
Make it mean something. Don't document that meaning, because (a) if you have to document it, it's raising questions not answering them and (b) you're not perfect and the poor you will always have with you.
Find the most authoritative reference manual you can find for every tool, every language you come in contact with. The question is not "how do I make it do such-and-so?", the questions are "what is it made to do?" and "what can I make it do?".
Do the onion-skin trick: read -- almost skim -- once, for fast comprehension, don't try to remember everything, just remember the new words and where to find them. Read it again, to remember which parts talk about which other parts. Read it again, to start understanding why those parts talk about those others. Only then should you even start thinking about asking yourself "how do I make this do X?".
Don't trust *anything* in any other book until you can tell what part of the authoritative reference it's talking about. Using C++? Pay the $18 or whatever it is now and read the ISO standard. Every book about C++ you read, tie what it's saying back to a section of the standard, and be sure you understand what both are saying. Using vim? Read the help. All of it. Do it again. Using MS Word? Hit F1 and start reading. Read everything. Using Python? Get the reference manuals and read them. Using TCP/IP? Read the RFCs.
Read The Fucking Manuals. Obsessively. Reread them again a month later. Then again a few months later. The questions are always: What is this made to do? What can I make it do?
Get used to it. I used to tell people I read manuals for a living. Classes are excuses to spend that much time reading the manuals. If you read the manuals, you won't need the classes. There is an *astonishing* amount of crap out there in the help books, useless "simplifications" that obfuscate the point of what they're supposedly explaining.
What worked for me every time I had or could steal the necessary time was, roughly, to overengineer the hell out of it, then boil out all the crap. Antoine de Saint-Exupery's maxim is absolutely dead-on: Perfection is achieved, not when there is nothing left to add, but when there is nothing left to remove.
With a little practice, most of the overengineering and boiling-out parts can be done in your head.
Particularly while you're new, reread your old code, constantly. Go find things you worked on before and read them again.
The rule is worded different ways in different places, but the basic idea is
A person is presumed to intend the reasonably foreseeable consequences of his voluntary act.
Shouting "fire" in a crowded theater is going to produce panic, probably physical harm and possibly trampling deaths. Any sane person knows this. "Presumed" has a legal meaning: the court takes it as given unless you show otherwise. This is the same reasoning used to outlaw "fighting words" in a bar, inciting riot, and so forth; it's why you can be arrested for driving drunk without actually killing anybody. It's enough evidence of criminal irresponsibility or actual malicious intent that punishment is warranted.
You're a little late to the party with that number. You're more than a hundred thousand dollars low for the canonical family-of-four.
Check
the OMB's own numbers straight from the White House on when that debt was rung up. Don't forget to check what it looks like when you correct for inflation; they've got those numbers in some of those too, easy to find. A little cut and paste and fill-down arithmetic.
You might think you own your house free and clear. Not really. Rich people effectively hold a mortgage on it, and you and your children will be paying interest on it until you pay it off. Guess who's getting rich on the interest we're paying on over nine trillion dollars of debt. Is it you?
Don't forget to find out who mortgaged your children's future. Don't believe anybody, because you can damned well bet the people who actually did it are lying to you.
Searching for the actual video might prove instructive. Whether or not she believed it was the right thing before her son was ordered to Iraq, she's not sure now, and the headline and leadin foully misrepresent what she said. The Agence France-Presse version that appears on military.com similarly misrepresents her meaning, but at least bothers to quote accurately and thus advertise its own misrepresentation.
So? Part of turning children into good, honest, decent people is training them not to give in to that desire. Not admitting mistakes when it matters is not good, not honest, not decent. It's malice.
Yes. If the notion of life on a neutron star would excite your kid's imagination, or you can work him or her around to that state, then do it. I'm not sure there is any finer demonstration of the value of respect, anywhere. The title is one awesome pun.
If she's got "power and confidence", then what the hell is she doing preying on little boys?
I mean, I see the elision you (or McSweeneys) are talking about, but I think the absence of mature sex drives is more intended to get the rest of the stuff in without complications kids are simply unequipped to understand than to pretend that they don't exist.
Very good! You understand the adjective "free". Now, let's get you working on understanding two-word constructions: in the phrase "free software", what noun does the adjective "free" modify?
Also, did someone admit that they received this e-mail but did not open it? I don't read that in the article.
Perhaps that's because you didn't read the article? That's the most charitable interpretation here, since both the title of the article and its first sentence point out their explicit refusal to open the email.
How do you see one of these Creatures in your Spore Creature Creator? Right Click on the thumbnail image of the creature. Save the image to your desktop. Drag the saved image from your desktop into the Spore Creature Creator. Voila! The Creature is in your game.
Whoever thought that up deserves a few moments of quiet respect.
That would be the fourth, prohibiting search in the absence of probable cause. Government agents are not permitted to demand your ID unless they've already stopped you for cause. They can ask, and most people (me included) don't mind just showing it in response to an even colorably polite request. But they're required to take "no" for an answer. That's kind of the definition of a free country.
The analogy I've liked best is distance: in this case, in the time it takes ars's God Box to get to the supermarket, this puppy has been around the world a few times.
Please forward me copies of everything you've ever written and everything you've ever received, and recordings of all your phone conversations. Plus all your travel records and every financial transaction.
If you won't do it for me, then please just pick anyone. Any ten or a hundred people, actually. Be sure to select only people who have appointed themselves your political enemies; who the hell else would ever bother looking?
Yes, look at it. Luciano Bello found it. He's a Debian developer. Please don't go off about how long it took to find it. Think about that: it makes GP's point for him.
And ook at the rest of the argument. ~Are you going to read every line~? C'mon: strawmen don't get much more blatant than that. Similarly with "Open source isn't a guarantee of anything." As compared to what, please? Another strawman.
First of all, Exherbo was announced because some elements of it will be discussed at an upcoming conference. [...] it seemed wise to at least let people know what was going on [...] Unfortunately Slashdot picked up the announcement because some tard decided it would be a great idea to submit it to them. We did not do that ourselves
This announcement is for the roll-your-own crowd. If you want a push-button install, wait for the Ubuntu guys to roll one up for you; when they've got it ready, Ubuntu will tell you, and you really will only have to push a button.
/. starts chattering about stuff so fresh out of the gate that it hasn't hit the distros yet. Installing unpackaged binaries, or installing from source, needs more knowledge about what the computer's actually doing when you double-click an icon. That's true on any OS, it's just that doing it is rare on Windows and common on Linux, so you're not used to seeing it discussed.
Slashdot Mirror
s,truly free,a coddled child
Your comments are written to answer questions that the people reading your code cannot readily answer for themselves.
Your procedure is:
Needless words are a complete and utter waste of time. If you're stuck in some PHB-driven environment that insists your comments provide unneeded answers, find some way of marking what matters. Right-justify the real comments, whatever works.
Whitespace is a language. Find the arbitrary parts in whatever style you're matching and make your use of them mean something that helps readers. Indent variable definitions differently, to subtly highlight them. One blank line or two?
Make it mean something. Don't document that meaning, because (a) if you have to document it, it's raising questions not answering them and (b) you're not perfect and the poor you will always have with you.
re the verbiage rule: the rest of Strunk & White is gospel also. Likewise Orwell's "Politics and the English Language".
Find the most authoritative reference manual you can find for every tool, every language you come in contact with. The question is not "how do I make it do such-and-so?", the questions are "what is it made to do?" and "what can I make it do?".
Do the onion-skin trick: read -- almost skim -- once, for fast comprehension, don't try to remember everything, just remember the new words and where to find them. Read it again, to remember which parts talk about which other parts. Read it again, to start understanding why those parts talk about those others. Only then should you even start thinking about asking yourself "how do I make this do X?".
Don't trust *anything* in any other book until you can tell what part of the authoritative reference it's talking about. Using C++? Pay the $18 or whatever it is now and read the ISO standard. Every book about C++ you read, tie what it's saying back to a section of the standard, and be sure you understand what both are saying. Using vim? Read the help. All of it. Do it again. Using MS Word? Hit F1 and start reading. Read everything. Using Python? Get the reference manuals and read them. Using TCP/IP? Read the RFCs.
Read The Fucking Manuals. Obsessively. Reread them again a month later. Then again a few months later. The questions are always: What is this made to do? What can I make it do?
Get used to it. I used to tell people I read manuals for a living. Classes are excuses to spend that much time reading the manuals. If you read the manuals, you won't need the classes. There is an *astonishing* amount of crap out there in the help books, useless "simplifications" that obfuscate the point of what they're supposedly explaining.
What worked for me every time I had or could steal the necessary time was, roughly, to overengineer the hell out of it, then boil out all the crap. Antoine de Saint-Exupery's maxim is absolutely dead-on: Perfection is achieved, not when there is nothing left to add, but when there is nothing left to remove.
With a little practice, most of the overengineering and boiling-out parts can be done in your head.
Particularly while you're new, reread your old code, constantly. Go find things you worked on before and read them again.
A person is presumed to intend the reasonably foreseeable consequences of his voluntary act.
Shouting "fire" in a crowded theater is going to produce panic, probably physical harm and possibly trampling deaths. Any sane person knows this. "Presumed" has a legal meaning: the court takes it as given unless you show otherwise. This is the same reasoning used to outlaw "fighting words" in a bar, inciting riot, and so forth; it's why you can be arrested for driving drunk without actually killing anybody. It's enough evidence of criminal irresponsibility or actual malicious intent that punishment is warranted.
a debt of $25000 per family
You're a little late to the party with that number. You're more than a hundred thousand dollars low for the canonical family-of-four.
Check the OMB's own numbers straight from the White House on when that debt was rung up. Don't forget to check what it looks like when you correct for inflation; they've got those numbers in some of those too, easy to find. A little cut and paste and fill-down arithmetic.
You might think you own your house free and clear. Not really. Rich people effectively hold a mortgage on it, and you and your children will be paying interest on it until you pay it off. Guess who's getting rich on the interest we're paying on over nine trillion dollars of debt. Is it you?
Don't forget to find out who mortgaged your children's future. Don't believe anybody, because you can damned well bet the people who actually did it are lying to you.
Searching for the actual video might prove instructive. Whether or not she believed it was the right thing before her son was ordered to Iraq, she's not sure now, and the headline and leadin foully misrepresent what she said. The Agence France-Presse version that appears on military.com similarly misrepresents her meaning, but at least bothers to quote accurately and thus advertise its own misrepresentation.
So the choice is supposed to be between being aggressive towards Microsoft and starting to "play nicer with them"?
How about a third option: wake up.
Don't throw arrows. Be diplomatic.
Good advice. Diplomats are not known for their trusting souls.
LaTeX is hard
Didn't Mattel get in trouble having Barbie say that?
(replying to undo mouse-o'd mod)
It's human nature not to want to admit mistakes.
So? Part of turning children into good, honest, decent people is training them not to give in to that desire. Not admitting mistakes when it matters is not good, not honest, not decent. It's malice.
Hal Clement - Mission of Gravity
Yes. If the notion of life on a neutron star would excite your kid's imagination, or you can work him or her around to that state, then do it. I'm not sure there is any finer demonstration of the value of respect, anywhere. The title is one awesome pun.
If she's got "power and confidence", then what the hell is she doing preying on little boys?
I mean, I see the elision you (or McSweeneys) are talking about, but I think the absence of mature sex drives is more intended to get the rest of the stuff in without complications kids are simply unequipped to understand than to pretend that they don't exist.
Very good! You understand the adjective "free". Now, let's get you working on understanding two-word constructions: in the phrase "free software", what noun does the adjective "free" modify?
Perhaps that's because you didn't read the article? That's the most charitable interpretation here, since both the title of the article and its first sentence point out their explicit refusal to open the email.
20972Mbbl reserves / 5.102Mbbl/day current extraction rate == 11.25 years before we run dry.
I'm having a hard time seeing how this fits in any argument for sucking the reserves dry faster.
So I go check it out, and I see this:
How do you see one of these Creatures in your Spore Creature Creator? Right Click on the thumbnail image of the creature. Save the image to your desktop. Drag the saved image from your desktop into the Spore Creature Creator. Voila! The Creature is in your game.Whoever thought that up deserves a few moments of quiet respect.
That would be the fourth, prohibiting search in the absence of probable cause. Government agents are not permitted to demand your ID unless they've already stopped you for cause. They can ask, and most people (me included) don't mind just showing it in response to an even colorably polite request. But they're required to take "no" for an answer. That's kind of the definition of a free country.
The analogy I've liked best is distance: in this case, in the time it takes ars's God Box to get to the supermarket, this puppy has been around the world a few times.
You asked ~are you going to read every line?~, as if he'd argued "if, and only if, you read every line, you can enforce your privacy and security."
Which he hadn't.
You refuted a flawed argument that he didn't make.
Please forward me copies of everything you've ever written and everything you've ever received, and recordings of all your phone conversations. Plus all your travel records and every financial transaction.
If you won't do it for me, then please just pick anyone. Any ten or a hundred people, actually. Be sure to select only people who have appointed themselves your political enemies; who the hell else would ever bother looking?
Do you think Richelieu's boast was empty?
True. Can we talk about the bad parts now?
We've got a long track record to look at. History says the crimes warrantless spying leads to are worse than the crimes it prevents.
Yes, look at it. Luciano Bello found it. He's a Debian developer. Please don't go off about how long it took to find it. Think about that: it makes GP's point for him.
And ook at the rest of the argument. ~Are you going to read every line~? C'mon: strawmen don't get much more blatant than that. Similarly with "Open source isn't a guarantee of anything." As compared to what, please? Another strawman.
Everybody knows a single divisor that division can't handle. Is division impossible?
This announcement is for the roll-your-own crowd. If you want a push-button install, wait for the Ubuntu guys to roll one up for you; when they've got it ready, Ubuntu will tell you, and you really will only have to push a button.
/. starts chattering about stuff so fresh out of the gate that it hasn't hit the distros yet. Installing unpackaged binaries, or installing from source, needs more knowledge about what the computer's actually doing when you double-click an icon. That's true on any OS, it's just that doing it is rare on Windows and common on Linux, so you're not used to seeing it discussed.