100 Days of Improving Coding Style

Day 6: Documentation

You’ve seen it all.

Comments in the middle of someone’s code. Sometimes they’re above, sometimes below. But what’s the “right way” to do comments?

Let’s look at the example. OK, right off the bat, WAY UNNECESSARY COMMENTS.

Now I know, this is an extreme example. No one really writes comments like this, right?

But lets use this example to transition to something a little less extreme. Say you had a line of code that was ambiguous to a new person looking at your code. You decide wait, let me just put a comment. And then, the slashes come out.

Now hold on there. I won’t argue that you should never use comments, and there may be a situation where a comment maybe needed in between code.

BUT, what I will show you now may minimize the amount time you take to document your code.

Ready? Let’s run with the example we used at the start. Instead of the above, lets move to this!

Take a look at that. No comments in the code. Just a clear description of what your function does right above it. Perfect!

Why do I like this? Because everything is clear. I don’t want to read English in between code. When I see code, I just want to analyze code.

Having a nice, short description above the function is super helpful and easy for other people to read. Instead of commenting every line, or every couple of lines, just write everything you need in the beginning!

Also, I like to capitalize variables and parameters because often they can be the same words you need to use in the description, so capitalizing reduces confusion.

I would like to credit this style tip to my old professor Paul N. Hilfinger. As I mentioned before this tip was apart of the style guide he made us adhere to, and now it has become a fundamental part of the way I write code!