How to Write Without Writing

I disagree on one point - you need more than a modicum of technical skill. There is a lot of well-commented bloatware, atrocious API designs which are meticulously documented, and even simple things like which parameters or when to split something into a set of functions that are badly messed up or never refactored.

Using a very fine typeface and perfectly formatting “Jabberwocky” doesn’t make it clear and transparent.

In some ways too much skill can be a problem (which is why C is great and terrible at the same time). If you are really skilled, you can actually write usable bloatware in the atrocious API as a monolith or as tiny fragments, but the higher skill is in knowing how to reduce the design and architecture so that you only need to be a mediocre programmer to implement it.

At that point, being able to communicate it effectively is a big bonus (especially the hows and whys), but I find either I can read the code (sans comments!) and from its existing topology and structure I can understand it, or it is an impenetrable gordian knot that no amount of gloss will reveal even if the translation into the colloquial speech is both credible and accurate. The medium is first and foremost the code itself. If that is bad, being able to explain it instead of fix it is not a plus.

Hi Jeff,

Let me preface this comment by saying that I do blog, often, about software engineering.

I think a lot of the problems that people have in writing a software engineering blog is that a lot of the time it feels like blasting a shotgun into the nether black. It’s actually pretty hard to get people to read your blog so that you can start having a discussion with your audience. It’s true that just writing your blog for your own benefit is a great idea for developing communication skills, but a feedback loop is definitely a step up. Stackoverflow is great for this reason, because when you ask your questions, or answer someone elses question, you have a feedback loop that will correct your aim each time, nearly always for the better.

What do you think is a good way to get the discussion started for those who have been writing software engineering blogs, but have no readership to build a dialog upon?

@ctrlShiftBryan and @Plasticsyntax

Maybe my communication skills need updating. I said this:

“It’s far more important to write clear code, than to write code that needs to be explained by comments and external documents.”

I’ve been doing this a long time now, and paying attention while I’ve done it. I don’t really need to be reminded what comments and documentation are for :wink:

However, both of you have made comments that I might have made 15 or so years ago, when I had only been in the business a few years.

Over my 20+ years doing this job professionally, I have come to the realisation that code that needs very much in the way of comments and/or documentation (in the traditional sense, at least) is bad code. The fact that Joel makes remarks like the one quoted is one measure of his skill.

You may need comments in your code, but they should be very rare occurrences. You may need documentation, but if I have to read both your code and your documents to understand any given piece of code, it means I’m going to have to maintain both your code and your documents. This rarely works well, either as a means to understanding, or as a practical matter keeping everything in sync. You should strive to make as much documentation as possible unnecessary.

Your code is far more important that either comments or documents, because there is far more of it (I hope!!), and you spend far more time looking at it.

Try to write your code without the need for comments. A comment explaining a block of code almost always means there is a method waiting to be extracted. A comment explaining a function/parameter/variable usually means there is a better name waiting to be used.

Try to minimise the documents you need. Your code should explain nearly everything about itself. Try and limit documents to things outside of the code, like working environment setup, for example. Critique the documents you already have. Do they still reflect reality? When did anyone last use them? Are these documents helping you deliver great software, or are they an unnecessary burden slowing you down?

@pauldwaite

Writing tests before code will get you cleaner code. Then you’ll find you won’t need all those comments.

Gerald Weinberg made the same observation in his 1971 classic, The Psychology of Computer Programming, that the most important language for a programmer to know isn’t a programming language at all, but English, as programming is primarily a social activity.

Great book, still highly relevant 40 years after it was written.

I entirely agree with this blog post. In fact it was Jeff’s comments that got me started with my own blog ( http://www.matthewedmondson.info ). Communication is massively important in software development - after all if you can’t communicate with other people how are you going to communicate with a computer?

I am not a programmer, so if you don’t want to sully yourself with what non-programmers have to say, stop reading right now. I do love this blog, because a lot of it is transferable to non-programming situations.

My uncle worked for Amoco for thirty years. He had two bachelor’s degrees, one in physics and one in chemistry, and he always said that the thing he did the most of in his career was write.

My mother taught Freshman English. Because she taught at a particular time, she always ended up with a lot of athletes in her classes, and after an assignment or two with students insisting that they didn’t have to revise what they’d written, the following conversation would ensue:
Mom: "Would you ever go to your coach on Monday and say, ‘Coach, I don’t feel like practicing this week, just play me on Saturday’?"
Students: [horrified] "No!"
Mom: "Why not?"
Students: "Well, you have to practice, or you won’t get any better!"
Mom: "Well, revising your writing–by doing multiple drafts, for example–is practicing your writing."
Students: "Ohhhhhhhh."
Her report that this Rubicon had been crossed was always a hoot around the dinner table. And most of the class then bought in to the “practicing your writing” concept.

You may be a programmer now – but you may not always be a programmer. You may be responsible for mentoring new programmers, or teaching programming. You may be responsible for writing project proposals, RFPs, or final reports. You may move into management, and be responsible for writing about your subordinates’, group’s, or company’s performance. You may (as someone noted above) have to explain to higher-ups what the heck you’re doing, and why you need to do it. Or you may do something else entirely. Strong communication skills are always a huge asset, because lots of people don’t have them…

Thanks, Jeff: I’ll be checking out the writers site…

I’ve always enjoyed writing as much as I’ve enjoyed programming. I started a blog about a month or so ago at http://www.keyboardandchair.com . I really don’t know jack sh*t about blogging, but I’m having a lot of fun doing it. I’m not sure if my theme of offensive and insulting tutorials will gain many readers, however. Either way I still laugh my ass off while writing them.

@Uala:

It is not about everyone person reading every single thing you post, but about the time when someone does finally read something you post, it being understandable enough that the point comes across.

Kind of like the newspaper intern who puts quality after quality into his work, only to have it overlooked time and time again… Eventually, when it is not overlooked and given a chance, won’t the hard work shine through then?

My other examples include references to The Day After Tomorrow, The Little Train That Could, and the beginnings of the internet :slight_smile:

Let me just add that this is another area where the socializing affects of the Internet and digital age are a myth. Oh sure, you might have hundreds of Twitter followers and be an voracious texter, but that’s not really, thoroughly communicating. 140 characters is to communicating what the appetizer course at a fancy restaurant is to the main course - it’s not really food. Oh it’s pretty - and pricey - but it’s not substantive.

Just as you said, I’ve found that blogging has given me an excellent opportunity to hone and showcase my writing skills. And it’s not just about being able to craft grammatically-correct sentences or even complex paragraphs. No, it’s about developing a style of writing that gets your point across, sure, but perhaps more importantly, it maybe even gives the reader some sense about who you are.

Sadly, as others have said, blogging can often feel futile. And this is where being a good “netizen” comes in - you have a responsibility to nurture your fellow man’s efforts by commenting on blogs. Sure, blogging should be it’s own reward, creative outlet and all, but even the most stalwart writer still needs occasional validation, some kind of feedback - be it good or bad - that let’s him know that his words are being read and might have some meaning to someone else.

From what I understand Jeff has not had a proper job in the area since 2008 ?

I remember when this blog used to be about programming, complete with actual code samples instead of opinions, I’m not really sure what it is about now, writing ?

@Jim Cooper,

I see your point. But I disagree on some of your points, especially the following:

You may need comments in your code, but they should be very rare occurrences. You may need documentation, but if I have to read both your code and your documents to understand any given piece of code, it means I’m going to have to maintain both your code and your documents. This rarely works well, either as a means to understanding, or as a practical matter keeping everything in sync. You should strive to make as much documentation as possible unnecessary. - Jim Cooper

Comments and documentation should not be rare or unnecessary. They should be common and necessary. Do you expect every programmer to understand the code you’ve written without checking any documentation? The purpose of comments and documentation is to give you first the whole picture. The code is there for the details.

Maintaining code that has no documentation is far difficult than code with documentation. If code and documentation aren’t necessary, why do these popular frameworks (for example frameworks for Java) have to write documentation? If people are smart enough, these developers don’t even need to put a special site detailing instructions or FAQs or even docs for their frameworks. All they need to do is post the zip file, and they should be done.

But you see a lot of people are thanking these people for writing documentation. They appreciate it. Then it means something. It means it helps them. Why would you deprive your fellow programmer of something that can greatly help him in his understanding? Is there anything wrong with that. I rather do extra work documenting than allow my fellow programmer struggle. After all, I’m a programmer. I know how difficult it is to maintain code that has no documentation. Believe me I had handled a big chunk of framework that doesn’t even have documentation.

"Over the last 6 years, I’ve come to believe deeply in the idea that that becoming a great programmer has very little to do with programming. Yes, it takes a modicum of technical skill and dogged persistence, absolutely. But even more than that, it takes serious communication skills: "

… and so you and joel decided to re-invent usenet really badly throwing away all the things that were learnt by hundreds of people about how client interfaces should operate in such environments.

@Dianneking71

I stand by my remarks. In particular:

Do you expect every programmer to understand the code you’ve written without checking any documentation?

Yes, almost all of the time I do. You may need to understand the problem domain (with or without documentation), but the code should stand alone nearly all the time. If it doesn’t then it’s bad code.

The purpose of comments and documentation is to give you first the whole picture. The code is there for the details.

Like I said earlier, I’ve been in this business a long time. I understand what comments and documentation are for. But I’ll say it again, my experience over 20+ years leads me to my opinion that comments and documentation do not make up for bad code. Good code, almost by definition, requires little of either.

Maintaining code that has no documentation is far difficult than code with documentation.

Not necessarily true. Documentation needs to be maintained along with the code (misleading documentation is worse than useless). That’s more work. Forever. For everybody who works on that code. So you should keep documentation to a minimum. This may or may not be zero, but if you can make your code understandable without documentation, that’s just got to be better. Most of the time that’s possible.

FWIW, the best code I’ve ever seen had no documentation at all (it had unit tests, which do the job better if done well).

If code and documentation aren’t necessary, why do these popular frameworks (for example frameworks for Java) have to write documentation?

I assume you mean comments and documentation, and I didn’t say they weren’t necessary. However, good frameworks require less documentation. If you have a framework that requires a lot of docs to be understood, I’ll argue you don’t have a well written framework.

I would point out that writing frameworks (ie code that is intended to be widely reused) is much more difficult than “normal” code. Which is why so few of them are very well written :slight_smile:

Note that useful != well written.

Believe me I had handled a big chunk of framework that doesn’t even have documentation

I’ve handled a lot of code too, framework and otherwise, over the last 20 some years of professional programming. I’m speaking from that level of experience. You don’t fix crappy code with comments and documentation, you need to fix the code. My experience also very strongly correlates lots of comments with very poor code.

I rather do extra work documenting than allow my fellow programmer struggle.

If I was your fellow programmer, I’d rather you did extra work improving your code so you didn’t need to document it :slight_smile:

Once upon a time, I thought as you did. Way back then, I was told that good code required comments only rarely. I didn’t believe it either :slight_smile:

Maybe there is no point giving people the benefit of your experience, and you have to learn some things the hard way. But I urge you to do a bit of research and give writing code that doesn’t require comments and docs a try.

Love this post.

Damn people really don’t like documenting their code huh? If anyone ever tells you ‘you don’t need to communicate well to become a great programmer’ my only advice is… ‘just smile and wave’.

Honestly this is exactly what i wanna hear always, since i am tying to trick myself be writing out micro-posts using twitter, emails and rarely blog posts. I liked the idea and the article, and as i am a technical community member i ll share this across community. Thanks again for the motivation

You just inspired me a lot. Thank you.

Very inspiring!

I started blogging on http://mcanti.wordpress.com/ inspired by CodingHorror!

I completely agree with this post and what a relief it is to read it from another programmer. I used to teach writing while in grad school and I often had Comp Sci students who were forced to take my class as part of their core requirements tell me how they didn’t belong in a writing class.

Why not? I would ask.

Because we’re computer science majors. We don’t need writing skills.

Argh!

Anyway, I’m a programmer and a writer and I have to say that in ADDITION to good communication skills (gone are the days where the 22 year old “genius” who can’t make eye contact and speaks only in code is considered valuable), close reading skills are a must. Let’s face it. Programmers have to do a LOT of close, careful reading in order to learn. I don’t know about you, but I do read a lot of programming books and I expect the same is true of those I work with. And I’m pretty sure that skim reading documentation isn’t the best way to learn.

I moved a post to an existing topic: The Importance of Net Neutrality