Change and growth are faster than ever in software these days. There’s Silverlight, LINQ and WPF from Microsoft. There’s AJAX, REST and Rails 2.0 in the web development world. Java has JavaFX. There used to be a time when you had to pick one language and run with it because it was just too overwhelming to master more than one. Now it’s impossible to keep up with new developments within even a single language. This has many developers scrambling to figure out what to learn next. No one wants to invest countless hours in a losing technology… you want to learn something that will be useful in the long run. I have just the skill for you, and it doesn’t matter what language you work with.
Learn to write well. [*]
“But that’s not a programming skill!” you’re probably saying. Or maybe you’re disappointed because you thought I was going to be talking about the very latest cutting-edge API you can’t live without. Good writing skill is probably one of the most useful talents you can develop as a software engineer, and ignoring it is one of the biggest mistakes most programmers make.
Working in a cave
I used to work with a programmer who we jokingly referred to as a “walking MSDN”. He knew all the Win32 APIs, he could tell you the int values of const definitions and could enumerate the parameter lists to functions overloaded 30 times over. As a programmer, when given an assignment, he would go into his cave, hammer out a solution and would re-emerge from his cave with something that worked. I mean that in the most serious way… he would hammer his code into submission until it worked. There was no such thing as elegant code to him; it worked or it didn’t.
His manager both loved and feared him because he would do everything required on time, but he had no idea what happened in that cave. There was no visibility at all into what he was doing, and his manager had to blindly rely on the fact that he had a history of getting stuff done on time.
Programmers loved and feared him because he was incredibly knowledgeable and could answer any question about how this or that API worked. But whenever someone had to get inside his code, it was a pure mystery. There was no documentation, no models, no code comments… nothing but the raw code itself. For mister MSDN, this was no problem, because it was all in his head. For everyone else, it was like being lost in a big city with no map.
Was he a good programmer? Most people that worked with him would say yes… he was technically proficient and met his deadlines. But most of those same people would also say that they had a very difficult time working with him. That element of fear that he generated was a direct result of not being able, or willing, to communicate. He couldn’t communicate his plans or designs to other programmers. He couldn’t communicate his status with his managers. He couldn’t communicate his interfaces with other teams. Eventually when he left, his code left a wake of terror felt by those that had to pick up where he left off.
The lifespan of a tech skill
Technologies come and go. Seven or so years ago, I felt like I was completely on top of my game when it came to programming technology, at least in the Microsoft world. I had a very deep understanding of COM and ATL, thanks to Chris Sells, Brent Rector and Richard Grimes, and I coupled that with VB6 on the front end. This was a really potent combination and I thought I’d be working with that for years and years. But, as with most technical skills, it didn’t last long… .Net came along a year later, ATL became outdated and VB6 just disappeared into the sunset. Now that I’ve mastered C#, I find that I haven’t even touched the new stuff in .Net 3.5. The point is, no matter what technology you learn, with very few exceptions, it will disappear or be overshadowed by newer technologies (and probably sooner than later).
Writing skills will last you a lifetime, though. You will always benefit from it, regardless of what language or technology your use, or whether you’re even a programmer or not. Good writing skills are universal and will never be replaced.
The golden rule of documenting software design
Try to document whatever you are working on. It doesn’t have to be the worlds most perfect UML and you don’t need an expensive tool to do it. In fact, Wordpad and Paint are sufficient, and don’t tell me you don’t have those. Write in a way that best expresses your intent and your thought process in coming to the design decisions you did. I have a golden rule of documenting software design:
Describe your design to others as you would have others describe their design to you.
When you spend the time to do this, you’ll find that many benefits will follow. You’ll get feedback from others that may have tried to solve a similar problem and have insight you may not have thought of. You’ll leave a clear trail to follow for those that work on the code after you. Most importantly, you’ll shed light on your work, which everyone who depends on your work will appreciate. Even if no one else reads what you write, you’ll still have worked through problems in your head that can only lead to better design in the long run. There is no downside to documenting your designs.
If that wasn’t enough, consider the fact that someday you may be looking for another programming job. You’ll sit down with other developers and managers in an interview and try to describe how great your technical abilities are. You are now one of the vast sea of programmers trying to get that job. With your resume alone, a company has only your answers during the interview to base their decision on. With your documentation in hand, though, you can show them in full detail the type of work you’ve done and give them deeper insight into your thought process than they could ever get from interview questions alone. Your documentation serves as a body of work that travels with you, long after you’ve stopped working on this or that code, and speaks for your experience.
Of course, these skills won’t write code for you. But think about how much time you’ve devoted to learning programming based skills. Think about how many books you’ve purchased and read about programming. It’s a huge investment in time and money to keep up with. The next time you have some free cycles to sit down and pick up something new, consider skipping the software development section of the bookstore and pick up a book about technical writing. Here are some good books on this subject:
Posted in 
Good article, but…
“There is no downside to documenting your designs.”
The downside is that it takes up time. Sometimes you are working under a deadline and you don’t have that time. There are always trade-offs.
Better to slip one deadline and do it right than slip every future deadline when people have to maintain your jibberish code.
“slip every future deadline when people have to maintain your jibberish code.”
Then pay me more, use real project management techniques, Business requirements -> technical design -> Development -> validation life cycles.
Don’t come to me the week after you need a miracle and expect me to walk on water – that sh*t takes preparation
If you want maintainable code, you have to be prepared to pay for it. If you want functionality NOW, then get over your bad self.
I run a dev team, somebody who can’t be bothered to document their code has no place here. It may seem like you are saving time a the moment, but the time and overall resource cost for the team who has to work around poorly documented code is not only high, but it affects the moral of a team operating under tight deadlines.
So I say, get over YOUR bad self Bob and keep the shop clean.
As others have said it often comes down to time. If I’ve got time I put comment blocks in code saying what each function or module does or explains anything really complex or unusual – e.g. coding in a particular way to work around a particular compiler bug or bug in some third party software it interacts with. However, when up against a tight deadline the first thing to go to the wall is usually the documentation.
I can definitely see the case for making time for documentation – I’ve had to pick up code sometimes that I wrote ten years ago (yes really) and add new features – I’d long since forgotten what I’d done and why I’d used a particular or strange way of tackling a particular problem! The presence of a few comments to highlight something out of the ordinary is the difference between updating the code cleanly and updating it and adding new bugs.
A good writing book that I would recommend is
“Writing to Learn” by William Zinsser
http://www.amazon.com/Writing-Learn-William-K-Zinsser/dp/0062720406/ref=pd_bbs_sr_4?ie=UTF8&s=books&qid=1205955599&sr=8-4
You next article should be on how to kick your idiot manager out of the driver’s seat so you can actually implement some of these well established methods and practices.
Another factor here is that the lack of documentation is a major contributor to the exponential rate of competing new technologies and languages we are swimming upstream against. Without naming names, would have new technology X had really been necessary if existing [working] solution Y had been clearly documented and usable?
Good point Dennis. I’ve got a CV that looks like the history of programming languages. Frankly if Microsoft’s documentation was fuller and included more examples of functionality then there would be a lot less dodgy code out there. I’ve done lots of Office automation code and the MSDN documentation from MS sucks. This leads to a lot of “try this and see if it works” code instead of logical coding to clearly documented interfaces.
This is really true in any technical field (heck, SOPs on any job would probably be helpful in any field). Great article Scott!
Why is it always the “idiot boss”?
“Why is it always the “idiot boss”?”
Because moving to management means running with the pack. Prevailing pack wisdom for the last decade or so has been that programmers are overpaid, under-motivated, and over-valued, so they should be ever more ‘productized’.
Garbage In Garbage Out
I dont think in today’s agile development world you need anymore documentation than Javadocs (or NDocs). Writing seperate documentation would be an overhead considering
you need to keep maintaining it along with the actual code.
documentation is important for API-like code, but for internals and locals, it only need be done where appropriate
that is, where you’re not on a component boundary, then very often code itself is the very best form of documentation – its important to make sure that you can write that clearly
Documentation is definately important. But well written, clear, well formatted code with simple things like sensible variable names can hugely reduce the need for documentation in the first place.
Your code should document itself, to some extent.
I agree that, to some extent, you can go a long way by commenting your code well. However, I don’t really agree that the code can document itself. You can’t express the rationale behind a design decision with a well chosen variable or function name. You also can’t express how your functions and classes work together to produce higher level functionality by writing nicely formatted code.
A document is a single point of information for your code base that can contain more verbose descriptions and diagrams… things you don’t want to see in the source code. Code comments are good at describing “What does this do?” but a document is needed to explain “Why was this done this way?”.
No matter how self-explanatory code is, it will usually only explain the “what” and not the “why”. Hence, comments may still be needed to explain the motivation behind a command.
Here are 13 tips on how to comment your source code so that it is easier to understand and maintain over time:
http://www.devtopics.com/13-tips-to-comment-your-code/
Can’t agree enough on good writing. As to idiot bosses, I find that there are two techniques to use when dealing with one (and it’s rare not to be)
(1) – Send an email with time estimates including documentation as an explicit item every time;
(2) – Refresh your resume every month and look to get out from under. The first technique in the “No Asshole Rule” for dealing with people like this is to leave and I’ve yet to find a better technique.
The only thing worse than no documentation is wrong documentation.
“The only thing worse than no documentation is wrong documentation.”
… which is exactly what you have when all of your precious documentation is out of date and irrelevant the second it is created because it is never kept up to date.
I guess this guy you talk about wrote most of the slickedit macro code? Ever look at that stuff? Horrid Horrid Horrid, no naming convensions, globals scattered all over the place, almost zero comments.
I’ve been a programmer for about 9 years now and I have been forced to deal with a lot of poorly documented and uncommented code.
In my experience the worst code is often the code that needs comments the most. Sometimes both of these things are about being rushed.
I think some developers get an ego boost out of it. It gives them a (false) sense of skill/power that other people need their help to quickly see what their code is about.
Um, guys, anybody who knows anything about programming isn’t impressed. People can’t read my sloppy handwriting either, that doesn’t mean what I wrote is brilliant just that my handwriting isn’t as good as 5th graders.
Time and laziness aren’t excuses. It dosen’t take any time to put a one line comment above each function and a short paragraph at the top of each source file when you are done.
Asperger’s and IT: Dark secret or open secret? Understanding this connection goes along way in understanding IT communication stereotypes…
This is an excellent post. Too bad some of the responses focus on the ‘cost’ of documentation in a developoment cycle. The cost of not documenting is higher.
The larger point of the original post is that good writing skill outlasts the acronym of the day, and has enduring value; documentation is but one. Another value of good writing skill is that it tends to disicpline one’s thinking and communication in general.
A final tidbit from the late Edsger Dijkstra: “Besides a mathematical inclination, an exceptionally good mastery of one’s native tongue is the most vital asset of a competent programmer.”
Probably you’d start to learn Unix/Linux and, perhaps, Python. These skills will stay with you for a very long time, and no big, evil Corp can depreciate or even sunset what you know.