Reward:
- 100exp
- 20 gold coins
- Readable code
I’m setting myself a little challenge this LD – and that is to properly document all my code. I’m pretty sure a lot of us aren’t very good at commenting (I know I’m not), so I’ve decided that now is this time to rectify this – and I want you to too.
“But natpat, surely commenting my code will take up precious time!”
Of course it will. However, think back to previous LDs. Have you ever:
- been frantically searching for a last minute bug only to find yourself layers deep in spaghetti code, not knowing what half of it does?
- wanted to look back at a previous LD project to see how you did something, not to be able to understand most of it?
- fallen asleep at your computer, woken up and forgotten what the last 30 lines you coded do?
I know I’ve done all of them, and had I properly commented my code I would have been able to save time on all of them.
“But natpat, shouldn’t “good” code document itself?”
Yes. But this is Ludum Dare. There are only 48 hours. Writing “good” code is usually not high on my agenda, and I’m sure it’s not on most other peoples. Therefore, comment it!
“But natpat, why bother?”
It’s a good practice to get into. If you force yourself to do it when time is scarce or when you don’t need to, you’re more likely to do it when you do need to!
“But natpat, it’s only code for LD22 and I’m probably not going to ever look at it again!”
Yes, but someone else might want to. There have been numerous times when I’ve wondered how someone has done something in a Ludum Dare game, and since the source code is available, I’ve taken a look and not been able to understand half of it. If you take the time to properly document your code, any programmer who read it will be able to understand it!*
So, who’s with me? Take a stand against undocumented, unreadable, un-understandable (that’s not a word) code and comment your code!
Helpful articles:
- http://particletree.com/features/successful-strategies-for-commenting-code/ - broad article on commenting techniques
- http://www.craigsefton.com/programming/tips-better-code-comments/ - general tips on improving comments