{"id":130,"date":"2010-01-12T23:23:10","date_gmt":"2010-01-13T04:23:10","guid":{"rendered":"http:\/\/littlesvr.ca\/grumble\/?p=130"},"modified":"2012-12-05T00:55:21","modified_gmt":"2012-12-05T05:55:21","slug":"remember-how-good-you-are","status":"publish","type":"post","link":"http:\/\/littlesvr.ca\/grumble\/2010\/01\/12\/remember-how-good-you-are\/","title":{"rendered":"Remember how good you are"},"content":{"rendered":"

I’ve been reading about literate programming<\/a>, and was reminded that most programmers don’t write comments in their code. Whether to write them or not is a question that’s asked all the time, in all circles – starting in school and all the way to teams of masters of the known universe like Linus (who I’m assuming is responsible for this<\/a>).<\/p>\n

In school I thought comments are good. I’ve seen a few people who felt the same change their mind once they started writing real software, and I was tempted to drop it myself, but I didn’t.<\/p>\n

I’ve had the same arguments with myself that you’re thinking of now. Should I document design, exceptions, explain what complicated code does, go over the assumptions, etc.? This post is not about that, it’s about something I’ve realised a few days ago – a thought that may be slightly original.<\/p>\n

Writing comments in my code makes me feel good. I’m not a design freek and my code goes through a couple of iterations before it’s even checked into version control, often followed by more restructuring when flaws are found. And then I write comments.<\/p>\n

I look over a piece of code and think – what the hell is this doing, here? Oh – that’s to handle the weird case of an idiot unplugging the USB stick before it’s done. Comment. Man this function is long and hard to read. Several comments throughout telling a story (this being possible explains why it’s all in one function). Wow, at this moment I can actually grasp how the entire subsystem works – comments on top of the class and every function. Why is this a member variable and not a local one? Oh yeah, I remember – that’s bizarre but it works. Comment.<\/p>\n

Did I manage to explain it? As I read my code I remember all the interesting, strange, unfortunate, and neat things I’ve done. And I write it down in plain english. I feel empowered when I can explain something that appears to be a terrible mess. I think this is why I still do write comments. And I know they’re useful because when I go back to my code a month later I can actually figure out what’s where using them.<\/p>\n

Maybe it will work for you too?<\/p>\n","protected":false},"excerpt":{"rendered":"

I’ve been reading about literate programming, and was reminded that most programmers don’t write comments in their code. Whether to write them or not is a question that’s asked all the time, in all circles – starting in school and all the way to teams of masters of the known universe like Linus (who I’m … <\/p>\n","protected":false},"author":3,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[],"class_list":{"0":"entry","1":"post","2":"publish","3":"author-andrew","4":"post-130","6":"format-standard","7":"category-safeforseneca"},"_links":{"self":[{"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/posts\/130","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/comments?post=130"}],"version-history":[{"count":3,"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/posts\/130\/revisions"}],"predecessor-version":[{"id":635,"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/posts\/130\/revisions\/635"}],"wp:attachment":[{"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/media?parent=130"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/categories?post=130"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/littlesvr.ca\/grumble\/wp-json\/wp\/v2\/tags?post=130"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}