I read a lovely article over at Coding Horror about a week back, and I’ve been thinking about how we programmers deal with code. To start with, I think there are mainly two types of programmers today. 1) Programmers who don’t care about the looks of their code, and just care about getting the product out the door, and 2) Programmers who follow all the rules they’ve read in books and on programming sites/blogs, i.e. documenting, indenting and beautifying their code.
But what Jeff Atwood says pretty much sums it all up:
I have a friend who works for an extremely popular open source database company, and he says their code is some of the absolute worst he’s ever seen. This particular friend of mine is no stranger to bad code– he’s been in a position to see some horrifically bad codebases. Adoption of this open source database isn’t slowing in the least because their codebase happens to be poorly written and difficult to troubleshoot and maintain. Users couldn’t care less whether the underlying code is pretty. All they care about is whether or not it works. And it must work – otherwise, why would all these people all over the world be running their businesses on it?
Till now, I’ve only worked on one group project. I’ve always coded for personal projects, and have written my code in a way which works for me. It’s only recently that I’ve started paying attention to what my code ‘should’ look like, so that it is easy to port and debug.
This has involved adoption of ScriptDoc, which I think is an interesting concept. Documentation is a very important part of your coding, since it saves you tons of trouble if your have ‘lots’ of code. Standardizing it will result in all programmers getting ‘tuned’ to analyzing documentation in a certain way. Also, to make the entire coding process fun, I’ve switched full-time to TextMate. Let’s just put it this way: everything you’ve heard about it, and some of the things you’ve not heard, are all correct. Auto-completion, macros, in-built syntax recommendation, and custom bundles makes it just the perfect companion for any coder looking to focus on the coding, rather than the code itself (the layout and formatting, atleast).
A few steps
Spending a hint of time after your coding quota for the day is over to just skim what you’ve just written to add comments here and there, remove unnecessary line-breaks, and add necessary line-breaks is a good habit. Brackets you can do without (or ones you need), indentations and things like that should also be taken care of. This hardly takes more than 15 minutes (I do it, I know), and the end product is code that is pleasing to the eye. When you sit down to it the next day, you will not feel like giving up the moment you start, because your code looks inviting.
I’ve always felt that the more tempting you make something to the eyes, the more easily your mind accepts it. Why should your code be any different?
6 Comments
As a person who is working for a huge company, I understand the need for proper coding, comments and documentation. It may be needed only if someone else will work on your code in future. It is true that users don’t care how the code is written as long as it works, but a bigger system might not be perfect and will have several bugs hidden. Fixing these bugs will be a gradual process. As we unearth those bugs, it becomes increasingly difficult to nail it down with improperly written code. You yourself can do it, with a little effort. But a second person will have to toil hard just to understand what you have written.
Believe me, I have seen such highly obscure code in my company, which has wasted much of my time just to understand what it does.
As for me, I like to do proper commenting because I myself will forget how I have implemented certain things. But a trade-off comes here between proper comments and the file size.
BTW, have you heard about a tool called DOxygen? It creates HTML or PDF documentation from the code itself. You just have to follow a certain syntax in writing the comments, which looks much like LaTeX.
I also should mention that proficiency with ‘neat’-ifying your code usually increases with your proficiency with the language. When I compare my applications’ source code from a year back with one’s from now, I can clearly see a difference in the way it’s written and documented.
Whenever software/application development comes into the picture (and I mean proper development, and not a side/individual project), 99% of the time one will be working with a team of people. When working like that, habits I’ve pointed to in my post help big time.
If you’re worried about file-size because of documentation, an external file is always a decent solution. Documentation tools, like you’ve mentioned, are plentyful if you just look around. I plan to start using PHPDoc myself :)
Just wanted to bring it to your notice, if you haven’t already.
The current CSS that you have fails to bring a horizontal scroll bar if the browser window size is less than 1008px, so the content to the right is not viewable. Although I comfortably use 1280x960 resolution, I think you shouldn’t be so harsh to 800x600 people. :P Let them scroll and read; that “punishment” is enough!
I actually noticed that yesterday, and I think that’s because my sidebar’s are positioned absolutely. I can’t remove that, because it’s a lot of me being lazy and a little bit of that being the cleanest way to do it.
I’ll throw in a notice at the bottom I guess :P
So, you’re developing a multiplayer game for facebook, hah :)
@Ramani » Heh! Yes. I knew someone would figure it out from that little code! Glad to see you here :)
Leave a comment
RSS feed for comments on this post. TrackBack URL