I often hear that more and better documentation is needed 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
When given a piece of code to work with, developers typically take the path of least resistance. 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 outdated.
The example above is small and simple, but problem is exacerbated when functions are larger and more complex.
Redundant Documentation
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 are best utilized writing code, architecting systems, and creating tests. Writing documentation should be done only 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. Documentation that is targeted at users of the code, not maintainers of it, is necessary and encouraged.
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.
By Lane Wagner @wagslane
Download Qvault: https://qvault.io
Star our Github: https://github.com/q-vault/qvault
The post Documentation Sucks and You Probably Do it Too Much appeared first on Qvault.
Top comments (1)
Balance is important in documentation. Both forms mentioned here are important, but ultimately the users are the bigger community than the maintainers. I could not agree more!