The Greatest Programming Tip Ever
We’ll start this one off with a link. Don’t worry, it is just an image (safe for work, too).
The Greatest Programming Tip Ever.
I laughed when I saw that initially, then the title hit me. That really is the Greatest Programming Tip ever. Or at least it should be on the list of top 10 Great Programming Tips, if there were such a thing. Regardless of whether you are working on an assignment for a class, a personal project, or a product for your employer, it is almost certain that someone is going to look at your code. Writing readable and easily maintained code is important for this reason, but for different reasons.
If you are going to be writing code for a class, you had better put some time in making sure your code adheres to your department’s style guidelines. For the computer science department at RIT, this was actually factored into our grades on labs and projects. Even if it weren’t, your professor is going to be more frustrated than impressed with a piece of code that lacks comments and is filled with ternary operators. Comment your code to explain things that aren’t immediately obvious to a first year CS student, name your variables to be descriptive of their function, and make sure your program flows well (no spaghetti code). This will make your professor happy, thus boosting your grades.
For personal projects, it is just as important to follow the guidelines above. While there may be no one grading your work, consider that friends, future employers, and future-you may look at the code later. Embarrassingly, I can’t even count the number of times I’ve rewritten those run-once-every-three-months kind of scripts because I didn’t take the time to comment them. And if I had put those scripts on a public source repository (which I fully plan to set up soon), employers would eventually see it. I want the code I present to the world to reflect that I am a proficient, clean coder. You should want that for yourself.
Now here is the big one, your employers. If you are working for someone, that almost definitely means you are working on a team. In this case it isn’t just a matter of writing readable code so you can remember what you’ve done when you later have to fix a bug in the code. No - things have become amplified to a factor determined by the number of people on your team and the number of those team members that have to maintain your code. I know from experience the pain and delays that can be caused by terrible code, and I won’t lie: it happened way more often than I’ve blogged here. It dragged down the morale of our project team, caused huge delays in our production (on the magnitude of weeks of developer time over the past six months), and made the codebase impossible to maintain cleanly. You do not want to be the guy that is responsible for that. Best case is you lose your job, worst case is management turns a blind eye to the project team hiding organic material in the corners of your office (give it a couple of weeks, you won’t enjoy it).
Go out and do some reading on writing readable and maintainable code. Aside of learning the basics of a language, it is the single greatest thing you can do to improve your abilities as a programmer.
Hi Robert,
I think this goes further than just the code. I know that agile programming is all for minimising the amount of documentation that is written to support the development process, but I think sometimes teams go to far and do not want to write anything down outside of their code.
I believe that this is very bad practice, especially when that code needs to be maintained over long periods of time. Somebody else may have to pick up your code a year or two later. Before they can even estimate the impact of a change, they’d have to read through all of your code to even get a basic understanding of where things are at. If there is sufficient supporting documentation available then this would not be necessary.
And like you said, it is important that all of the documentation, internal to the code or external, must be done in a consistent and professional manner.
Keep up the good work,
Bruce
http://www.e-lm.com
Aug 28th, 2007 at 5:05 pm
You can’t really stress this point enough (not only to ‘young programmers’, but to the older ones as well). If you think the lack of comments is bad in the software industry, you’d probably want to kill yourself if you glanced through some of the code the hardware industry produces (think: very little to no formal computer science training). If I had a nickel for every time I’ve heard, “In the code,” as an answer to the question “Where’s the documentation?”..
The point I like most that you make here is that every thing you produce should be documented!! I’ve written a ton of small scripts to help me at work. When I showed a co-worker how to use one of them, he wanted to show others and it spread from there. The problem - my scripts were just hacks I made for myself, not intended to be distributed like that. So when they requested a few more features/options, I had to go back and completely rewrite them to be more robust and usable by people other than myself (which meant adding a –help option and comments so that the curious/maintainers can see what the script actually does). As I have a tendency to like compressing as much logic as I can into one line (see: ternary, nested ternary, and perl’s wonderful one-liners), this was quite a pain for me. These kinds of statements aren’t forbidden (in fact, many times they are encouraged) as long as you describe the logic. But, the good thing is I have certainly learned my lesson and now I comment every thing I write - even if it is a quick script just for me.
Aug 28th, 2007 at 8:02 pm
@Bruce:
Great contribution! It is absolutely true - everything should be documented.
@David:
Design is an important part of programming. Code written by CS people is bad enough, I would probably die if I ever had to read undocumented code written by hardware people :)
Aug 29th, 2007 at 1:30 pm