The Real Reason Silicon Valley Coders Write Bad Software
Halibutboy Flatfish stashed this in Tech
If you can't write... you can't write. As programming technologies, tools, and techniques move the human-computer communication frontier more toward the human side, this will become ever more true.
This article posits that "self-taught" programmers are LESS able to write coherent sentences or sustain complex thoughts than CS grads. Um... my 12 years at the University of Chicago beg to differ.
You're right, self-taught has nothing to do with it.
Most developers can't write well because they did not value that skill before they became programmers.
Even the best of these APIs are hard to use because the documentation, supposedly written in English, is terrible. Most engineers can't write a single coherent sentence, never mind string together a paragraph.
In order to write a person must first learn how to THINK.
In my experience, the kind of explicit writing instruction described in Peg Tyre's Atlantic story enables people to write powerful sentences -- and sometimes, when tempered with genius, great short stories. But this advanced degree of writing ability is also key to helping our country maintain its competitive edge in technology.
Steve Jobs once famously said that all the minutes wasted through bad software add up to lifetimes lost. If all the programmers I've worked with in my career had had good writing instructions, they would have been forced at an early age to think clearly, to communicate complex thoughts, and to combine simple ideas into compound ideas. These ideas, later written as code, would have resulted in better products. As I see it, our country's ability to maintain its technological advantage is very much intertwined with this discussion about teaching explicit writing skills in our schools.
The point of Tyre's article is that we need to teach people how to think. Once you can think, you can, with the right instruction, learn to write a good sentence. Once you can write a good sentence, then, and only then, do you have a shot at writing a great short story -- or code that can change the world and help maintain America's leadership position through the 21st century.
The writing article referred to by that article makes some good points. I would like to see a complete and concise guide to teaching writing and thinking from the basics.
Agreed, that article is excellent.
Also, isn't the point of school to teach us writing and thinking from the basics?
That seems like it should take a lot of time to learn and practice.
Unfortunately, it seems that everything is behind a paywall with intensive engagement. Hopefully they will write a thorough book at some point.
@AdamRifkin: Sure, but A) I'd like to be able to analyze whether particular programs are effective and B) I'm into thinking about alternative, potentially better ways of teaching such things.
This is another source of supposedly good teaching techniques:
Thanks Stephen. I guess they're behind a paywall because it's valuable.
Originally, I was indignant when I read this article, but once I dug up his linkedin....
... let's just say that now i'm contemptuous...
and spontaneously giggling.
Not sure why. He's a full stack dev. Seems legit.
also, I think he was intentionally being hyperbolic and I totally fell for it
He might have been intentionally being hyperbolic.
Or at least ironic since he himself is not a great writer.
Improvements in machine learning and artificial intelligence mean that more programming in the future will be done by bots.
Which means that the ability to write a specification -- and the ability to train a bot through communication -- will become an increasingly important skill to guide their work.
Well one thing I'm certain of, based on my over 20 years in software (not as a developer): most developers do not document their code. If they manage to produce a spec, it is almost always terrible. Usually they don't even get that far.
Now the excuse I've received over and over and over is that the code should speak for itself. Well that's a joke of a cop-out. In my experience, most developers have a hard time remembering the specifics of what they coded yesterday, forget a year ago. The best approach I've seen is a methodical and standardized code commenting scheme. Comments are written inline with, and at the same time as, the code. The comments are then pulled out later to fill in the details of a spec.
If the comments do not strictly follow an established style guide standard they are usually garbage, because you will spend more time trying decipher them than you would the code directly.
But it is a rare outfit that has any kind of style guide, or standardized coding method. If they do have one, they almost never stick to it. The pressure to hack the code is always enormous, and it's usually due to a combination of laziness, impatience and deadlines. Decent commenting is, at best, an afterthought. I have yet to see legacy code that hasn't mutated into a hairball, whether we're talking enterprise level solutions or mobile apps.
So in my experience, isn't that people can't think. It isn't that they can't write. They just don't follow a standard. Good writing, hell good communication, starts with a standard pattern. It is predictable. It is easy to follow. That said, you can learn all the good communication patterns out there, but if you don't as team, or (better) as a company consistently and continually enforce them, then they are useless.
Everything you're saying could be 100% correct but I would also say that code commenting is like education in that most people haven't thought hard enough about what their actual goals are. I would say there are at least 4 major reasons to comment:
* Laying out an API (e.g. this is the object, these are the methods of that object, these are the arguments they take). I suspect from your comment that this is the usage type you're advocating, and it can be very useful especially for large distributed projects. However the truth is that ACTUAL PROGRAMMERS WHO USE THE API rarely get anything but the basics by using this type of documentation, because the structure that you like tends to erase what you really want to know in favor of some abstract standard. I'll give you an example: Java API docs can often show you dozens of different ways to achieve the same goal, but they don't show you WHICH ONE IS PREFERRED or why until it is too late. That's why application programmers tend to just grep the codebase and see which methods get used the most by the people that actually build things with that API or in public cases rely on community comments.
* Guideposts to later maintainers of the code. These tend to be quick in-line comments like "TODO: refactor this mess" or "The reason for this odd structure can be found in Ticket #1234".
* Pseudocode. Many of the best programmers I know work by writing a short set of statements about what they are trying to build and why, and then expanding each statement into working code. If these comments could be extracted they might be of immense value to everyone in the organization -- especially anyone in QA or product -- but they rarely are. Also, this is the nub of the issue: programmers who work this way are the BEST ones, the ones who can write clear statements, and their code tends to also be clear! The issue is that if you can't write clear pseudocode, you generally can't write clear code either... and those are the programmers we all want to document more? Doesn't make sense!
* Programmer expression. Sometimes code comments are the purest expression of the feelings of the person working on it. Might not be professional -- my first day of work in Silicon Valley I was told that I should never swear in code comments, and I still don't -- but until code is written by robots it will continue.
This isn't even the full list I can think of off the top of my head, just the main ones. So because we can't even agree on the purposes, the audiences, the methods, and who should be writing the documentation... how can we possibly agree on what good documentation is?