photo 1546199881 3454b82b832b

Documentation Sucks and You Probably Do it Too Much

I often hear that we need more and better documentation in the tech industry. I’ve since come to believe that most documentation is overrated.

When Documentation Sucks

Incorrect documentation is worse than no documentation, and redundant documentation is worthless. Let’s remove the chaff.

Incorrect Documentation

Developers typically take the path of least resistance when given a piece of code to work with. When provided a function with a comment, most developers will read the comment instead of reading the code itself.

// changeDelimiter changes a comma delimited piece of textual
// data to a colon delimited one
func changeDelimiter(sentence string) string {
	words := strings.Split(sentence, ",")
	return strings.Join(words, " ")
}

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, the code becomes much harder to understand. The reader doesn’t know if there is a bug in the code, or if the comment is incorrect or outdated.

The example above is small and simple, but the problem becomes exacerbated when functions are larger and more complex.

Redundant Documentation

clone storm troopers

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 primary source of information (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? When functionality changes 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.

When is Documentation Good?

Documentation For Users

The examples above only apply to internal documentation, that is, comments and READMEs whose intended audience are the future developers of that same codebase.

API, CLI, and library docs are important. When we target documentation at users of the code, not maintainers of it, it is necessary and we encourage it.

Comments Should Explain ‘Why’ not ‘How’

Not all documentation intended for maintainers is bad.

Comments and documents that explain WHY something is happening are quite important. Comments that explain HOW the code works are most likely redundant and lazy. For example,

func exampleEndpoint(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 exampleEndpoint(input string){
	// clean input for use in a valid regex format
	input = strings.ReplaceAll(input, "^", "-")
	input = strings.ReplaceAll(input, "?", "_")
	...
}

A comment that explains that carets and questions marks are removed for later use in a regex is an example of good documentation that can’t easily be expressed in code. (This is used for example purposes and I realize that this is a horrible way to clean data for a regex)

These are just some simple rules of thumb I apply when deciding when to write documentation. They are by no means dogmatic rules, but I often see that management and developers being on-boarded to a project ask for extra documentation that probably shouldn’t be created.

More good engineering practices:
Lint on Save With VS Code Official Golang Extension
How To Build JWT’s in Go (Golang)
Simple Setup – Vue Linting in VS Code

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

%d bloggers like this: