{"id":863,"date":"2014-10-03T14:48:51","date_gmt":"2014-10-03T14:48:51","guid":{"rendered":"http:\/\/www.visionriders.com\/blog\/?p=863"},"modified":"2014-10-03T14:48:51","modified_gmt":"2014-10-03T14:48:51","slug":"comment-everything","status":"publish","type":"post","link":"https:\/\/www.visionriders.com\/blog\/2014\/10\/comment-everything\/","title":{"rendered":"Comment Everything"},"content":{"rendered":"

There’s a lot of programmers out there that are big fans of “self-documenting code”. That is, code that is easily understandable without comment lines explaining it. Robert Martin<\/a>, in his book Clean Code: A Handbook of Agile Software Craftsmanship<\/cite>, even goes so far as to say:<\/p>\n

The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures.<\/em> We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration.<\/p><\/blockquote>\n

(Emphasis mine.)<\/div>\n

The philosophy here is “your code should speak for itself”. After all, a programming language is a language<\/em>, right? We don’t need asides just to get through a block of pure English text, do we?<\/p>\n

The thing is, programming languages are not one-to-one equivalents to a human tongue. For that reason I follow a different philosophy, as you can probably tell from this sample of some C++ code I wrote:<\/p>\n

\"Well-commented<\/p>\n

Some of you out there who are programmers are probably cringing right now looking at that. Take, for example, the c = file->peek()<\/code> line at the bottom. Anyone with experience in C++ would recognize at once what I’m doing. Really, anyone familiar with file input\/output in general should understand what I’m doing just from the “peek”. I’m looking ahead one character in the file, without advancing the file reader, and storing the value in the character variable named “c”.<\/p>\n

Yet despite that, the line is proceeded by a comment: “Peek at the next value.” It describes the obvious. Some would say it’s useless and redundant. But I purposefully took the time to type it out there anyway. As you can probably see, I’ve even done it more than once.<\/p>\n

I strongly believe code should be well-formatted, organized, and easy-to-read, but also extensively commented. Why? There’s several reasons.<\/p>\n

    \n
  1. It keeps me focused. I type out what I’m trying to do right before I go about it, so I have a good idea how I need to format the code to best accomplish whatever task is at hand. When you look at my comments, you’re not just seeing what I’m doing, you’re seeing the entire thought process behind it.<\/li>\n
  2. It helps me keep my code organized. I can easily skim through the comments to find the chunk of logic I’m looking for, without having to dig too deep into the code itself.<\/li>\n
  3. It makes it easier for me to find mistakes. Occasionally I can spot a bug by just running through the comments and seeing the thought process doesn’t line up. I’m missing a step! Other times, I’ll actually find bugs by seeing that a comment doesn’t match the code that follows it. My implementation is wrong because I goofed and wasn’t following the logic that I’d stepped through in the comments.<\/li>\n
  4. Building on point 1, it reminds me what I was thinking when I wrote the code. A lot of times I’ll wonder, “why did I write it this way?” Then I’ll go back over the comments and remember. It’s saved me rewrites before, especially when I’ve forgotten that I already<\/em> tried what I might think is the “better” way and realized it won’t do what I need it to.<\/li>\n<\/ol>\n

    According to Google’s C++ coding style standards<\/a>, when writing comments you should “assume that the person reading the code knows [programming] better than you do.” I for one don’t. I assume that the person reading my comments is an idiot. Because I will be reading them later.<\/p>\n","protected":false},"excerpt":{"rendered":"

    There’s a lot of programmers out there that are big fans of “self-documenting code”. That is, code that is easily understandable without comment lines explaining it. Robert Martin, in his book Clean Code: A Handbook of Agile Software Craftsmanship, even goes so far as to say: The proper use of comments is to compensate for […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[22],"tags":[],"class_list":["post-863","post","type-post","status-publish","format-standard","hentry","category-programming"],"_links":{"self":[{"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/posts\/863","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/comments?post=863"}],"version-history":[{"count":11,"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/posts\/863\/revisions"}],"predecessor-version":[{"id":874,"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/posts\/863\/revisions\/874"}],"wp:attachment":[{"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/media?parent=863"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/categories?post=863"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.visionriders.com\/blog\/wp-json\/wp\/v2\/tags?post=863"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}