All too often have I seen comments like this. That’s if I’m lucky enough to see comments at all! I’m quite a big advocate of comments in code. I don’t agree with the age-old philosophy of:
If the code was hard to write, it should be hard to read as well!
I read a cool article this morning called In Praise of the Lowly Comment, which I think hits the mark nicely. I think I might just email this link around to my current workmates, as I don’t think they realise that commenting should consist of more that ‘TODO’s.
November 14, 2006
I’m definitely a big fan of comments. I found it especially helpful when I first started out to understand what the code was trying to do and why that particular way. Makes things a lot clearer and you’re not stuck for hours scratching your head asking “WHY!!!!” or bugging your team mates who have better things TODO!
November 14, 2006
You won’t get any argument from me on this issue. Comments are invaluable in code maintenance, though perhaps not as important as clear, easy to understand code.
However, you often find in code comments like this - “// Fuck, I know this is shite, just do it this way cos it’s easiest” followed by some ugly hack. Apart from in the most exceptional ciscumstances, this smells of a short term hack that’s gonna cause much long term pain months (if not years) later.
November 15, 2006
The problem is that by the nature of the software we create there are always going to be some bits of code which are difficult to read without having comments to back them up. Some code is just begging for comments regardless of how well it is written.
Chances are that someone at some stage down the track will have to figure out what you’re doing. There’s a stronger chance that he/she will be stupid
Comments are free! And while I don’t think they should be thrown around the code arbitrarily, they should be there to explain the more complicated sections of code. I do think that too many comments can be a bad thing (for the reasons discussed in the article), but not enough comments is just bad form.
November 15, 2006
Im currently having to update and get working an old .NET/Flash app on a new server.
No comments - ANYWHERE. Which makes it especially hard when there is also no database ERD or documentation, and nothing in the Flash files to help out either.
NOT commenting is a big peeve of mine, as I know that while it may have been hard for me to do the job in the beginning, I know the next person will also get paid, but they shouldn’t have to re-invent the wheel to get the job done (which is what Ive practically had to do in this instance).
I’d take commenting a step further and add a wireframe into the picture (for a job like this) which shows in a simple way, the relationship between all the elements and a brief description of what each does. Only adds an hour onto a job, but saves sooo much time in the long run.
March 19, 2007
hi all. nice blog. its very ineresting article.