Comments Suck and You Probably Write Too Many
The post Comments Suck and You Probably Write Too Many first appeared on Qvault . I often hear that we need more and better comments in the code we write. In my experience at previous companies as well as at Qvault , we often need better comments, we rarely need more, and often we need less. Before you crucify me for my sacrilege, let me explain. #1 – Incorrect Comments Incorrect documentation is worse than no documentation, and redundant documentation is worthless. Let’s remove the chaff. Developers typically (and rightly) take the path of least resistance when trying to figure out what a piece of code is doing. When provided a function with a comment, many developers will read the comment instead of reading the code itself, especially if the function is long and complex. Let’s take a look at this trivial example: // replace changes all the commas in the text to colons func replace(s string) string { strings.Replace("s", ",", " ", -1) } Whe...