Comments Suck and You Probably Write Too Many

Comments Suck and Your 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)
}

When another developer decides to use this function, they expect that commas will be replaced by colons. As this code clearly shows, however, the commas will be replaced by spaces. Because of the incorrect comment, a reader may take the comment at its word and introduce a bug, they may “fix” the comment and leave an existing bug, or they may “fix” the code and introduce a new bug. The point is, a bug is very likely to be produced if the reader isn’t careful.

The solution would be to give the function a more descriptive name and delete the comment entirely.

func replaceCommasWithSpaces(s string) string {
        strings.Replace("s", ",", " ", -1)
}

#2 – Redundant Comments

It would have been strictly better to omit the comment in the example above entirely. The developer would have been forced to go to the single source of truth (the code) and would have interpreted the meaning correctly.

Comments and documentation should, to some extent, follow the DRY principle (don’t repeat yourself). If the code clearly states what is happening, why add a comment? If functionality changes then two things need to be updated! If the code doesn’t clearly state what is happening, then a developer’s first instinct should be to make the code more readable, not to add a comment.

Redundancy is also quite simply a waste of time. Developers remain best-utilized writing code, architecting systems, and creating tests. We should only write documentation when absolutely necessary.

#3 – Comments for the Outside World – AKA Documentation

As we try to weigh the necessity of adding a comment to code, we need to take into account that it’s more likely that a comment is needed if it exists at an architectural boundary. For example, when writing a package or library we don’t want the users (other developers) of our code to have to worry about the internal workings. The function and class names along will well-written comments (or API docs as the case may be) should be all they need to understand how to use our APIs.

#4 – Comments Should Explain ‘Why’ not ‘How’

Comments and documents that explain why something is happening are quite important and don’t apply to any of the previous criticisms I’ve made of comments. Comments that explain how the code works are often redundant and lazy. For example,

func cleanInput(input string){
        input = strings.ReplaceAll(input, "^", "-")
        input = strings.ReplaceAll(input, "?", "_")
        ...
}

Here it is clear by reading the code that all instances of carets and question marks are being replaced by dashes and underscores… but why?

func cleanInput(input string){
        // clean input so that it can be used in a regex
        input = strings.ReplaceAll(input, "^", "-")
        input = strings.ReplaceAll(input, "?", "_")
        ...
}

A comment that explains that carets and question marks are removed for later use in a regex is an example of a good comment because it’s often hard to express the “why” in code.

Hopefully, these rules of thumb help when you are trying to clean up your code and write better comments. As always, let me know on Twitter if you agree or disagree.

Thanks For Reading!

Follow us on Twitter @q_vault if you have any questions or comments

Take some coding courses on our new platform

Subscribe to our Newsletter for more programming articles



source https://qvault.io/2020/10/29/comments-suck-and-you-probably-write-too-many/

Comments

Post a Comment

Popular posts from this blog

Why is Exclusive Or (XOR) Important in Cryptography?

Image
If you are getting into cryptography, or just trying to understand the fundamentals, you may have noticed that the exclusive-or operation is used quite often, especially in ciphers. What is XOR ( ⊕ )? XOR, or “exclusive or” operates on binary data. It returns true if both of its inputs are opposites (one false and one true), otherwise, it returns false. An example in go code would be something like: func exclusiveOr(a bool, b bool) bool { return a != b } XOR Cipher – The Perfect Cipher The XOR operation can be used as a simple cipher for encrypting and decrypting messages with a single key. This is known as symmetric encryption. It is interesting to note that if: The key is the same size as the message The key is kept secret and generated truly randomly Then the cipher is impossible to crack. This is known as a one time pad . However, a simple XOR shouldn’t be used in production due to the key length needing to be too long to be practical. Cipher Example A...
Read more

Base64 vs Base58 Encoding

Image
By Lane Wagner –  @wagslane  on Twitter Base64 is one of the most popular encoding formats for representing data. Have some binary data? Base64 encode it for convenient readability and parsing. Base58 is just another encoding format (with 58 characters instead of 64, and has gained popularity largely due to Bitcoin and other cryptocurrencies. When it comes to data encoding, there is typically a trade-off made between: Human Readability: Do humans have a good idea of what is being represented at a glance? Efficient data compression: How many bytes are used to represent the same data? Let’s rank Base58, Base64, and ASCII encoding against each other using these metrics! First: A Note on Binary All data is stored in a raw binary format on computers. These encoding formats (Base64, Base58, and ASCII) are just different ways of reading and writing binary data. For example, in Base64 the binary code 000000 represents the letter A , but in ASCII the binary 00000000 repres...
Read more

(Very) Basic Intro to Hash Functions (SHA-256, MD-5, etc)

Image
This is going to be a basic introduction to hash functions. I will assume most of my audience is here to gain an understanding of why hash functions are used and the basic idea of why they work. My goal is to explain it in a general sense, I will be omitting proofs and implementation details and instead focusing on the high-level principles. Why Use A Hash Function? Hash functions are used all over the internet in order to securely store passwords, find duplicate records, quickly store and retrieve data, and more. For example,  Qvault  uses hashes to extend master passwords into private encryption keys. A longer list of uses here:  https://en.wikipedia.org/wiki/Hash_function#Uses I want to focus on several important features of hash functions, arguably the most important features. Hash functions scramble data deterministically No matter the input, the output of a hash function always has the same size The original data can not be retrieved from the scrambled d...
Read more