Sunrise in the fog

    Commenting Our Code

    I've been writting software for a while now, more than ten years. When I first started in highschool, my teacher would talk about commenting code. I, being in high school (and writing stuff like "Hello World") thought, "comments, that's dumb".

    Fast forward to today. I'm writing large components and sites. State management, views, controllers, APIs, etc. Little bit more than "Hello World". And I gotta say, apologies are in order.

    No matter how good we developers are at naming things, we aren't good enough. I can look through an interface, and no matter how good it's named I will find methods I have to double take and really dig through to understand. If there's a bug I'm trying to fix? Layers of functions to go through. All of them with variables that become less and less understandable as the names become more vague. 

    That is, until some benevolent developer comments their code. Description of the function, each of the parameters (with their type if the language isn't typed). What it returns. Now I understand the use of comments. I can easily read through code and see what it does. Obviously it helps when code is well structured (another topic for another time), but comments are invaluable.

    Now... how do I structure my comments? A bad comment is almost as bad as no comment, so while there's no right or wrong way there are better and worse ways. I try to add the description, something for each parameter (type and short description), and the return. Here's a general example of what I do:

    [gist src=https://gist.github.com/benrgreene/330565fca480c534eddfef9970d28d95 file=comments.js][/gist]

    It's a lot. When I first started getting into the habit of commenting, it was hard. But now that I'm used to it, it's like second nature. I write the function stub, comment it, and then fill it out.

    As an aside, I've added key bindings to Sublime Text on my machine that allow me to easily add these block comments, and in case it might help here it is:

    [gist src=https://gist.github.com/benrgreene/237bba7ee4b46a85ad6cecf2719f0dd5 file=comments.json][/gist]

    One final note, it's hard to write good function descriptions. I really don't have too much I can say about what to write other than straddle the line between general and detailed. You shouldn't have so generic a statement that people don't understand really what's going on (i.e. don't put "makes an element"), but you also don't want an essay on what the function does either. It'll take practice - but if I can do it, anyone can.