Does extensive documentation do more harm than good?

#opensource #showdev #discuss #github

I feel like I tend to write too much documentation in code, PR descriptions, PR comments, JIRA tickets, markdown files, etc. If I can write documentation on it, then you bet that I am doing it 😆 There are few exceptions where I don't write documentation such as self-explanatory, 1-liner code... I think I do it because I don't like people asking questions. Really anti-social behavior 😊 Some may say that I have obsessive-compulsive disorder.

Warning! The following GIFs may cause siezures as they have been sped up to meet maximum file size limits.

I'm writing documentation in code, extensively...

Useful? Not useful? Who cares? No one? Readable? Beautiful?

I'm writing howto pages for all APIs, functions, and entities in the library...

Cool? Or insane? Or cool but a waste of time?

It looks like this in the mobile GitHub app...

Tell me it's not pretty... Tell me! (Please don't tell me).

I'm using GitHub Pages as a free website for my hard work on my documentation...

Can't really turn down a free domain and 1-click theme changes 😄

I'm writing really long responses in my open source discussion pages, issues, and PRs...

Because I want to make my collaborators feel heard and appreciated.

These insane tendencies carry over to my professional life. I write really thorough, detailed JIRA tickets, Slack messages, architectural docs, engineering notes, to a point of insanity. Typically, when I post my response to people at work, they usually don't have any follow up questions. They expect that if they ask Vandolf a question, he will answer that question and give every bit of context related to it with links to supporting documents and visual aid (GIFs and videos with callouts) when needed. It is probably starting to annoy some people at work despite them publicly giving me praise for it.

I don't have a GIF for this part because I don't want to get fired 🔥

It also carries over to my personal life, which I will not discuss here...

So... Lately, I've been wondering if I'm wasting time being so... thorough and a bit of a perfectionist. I spend more time documenting than actually writing code. I guess it reduces the bus factor and at the same time makes me super dispensable because everything I know is documented. So they can just fire me and let someone else take the lead 😁 The upside to all of this is that I am able to completely disconnect from work. I can completely discard all work-related thought (may that be private or open source) because I know that when I resume, I would not have lost any context due to my poor memory.

Thoughts?

DO I HAVE A PROBLEM? Is something wrong with me? Am I trying too hard? Being too anal? Should I calm down? Relax? Find something better to do? Why am I even doing all of this? Is there such a thing as too much documentation? Do people even read documentation? How do you interact with people like me? Is it tiring for you? Does it make you not want to talk to me because then you will feel committed to reading a blog as a response to every single one of your questions?

Top comments (5)

William Cairns • Jan 3 '22

As an experienced Developer and Technical Lead for a development team I dislike so many comments wihtin the source code. There are a number of reasons for this

Once changes are made to the code the comments are out of date unless updated as well, which means we have to update two places (DRY)
Comments that are out of sync with the code are a negative when trying to make changes/bug fixes. They make it difficult to understand what the code is doing, because it doesnt match the comment.
A lot of comments in source code makes it difficult to read the source code and build a mental model of the code itself. As Doctor Bob says in Clean Code - the use of comments is always because we could not express ourselves in code well enough

So I strongly dislike comments in code files

Documentation is another story. Good documentation about the library or functionality is a god send! I always support making good documentation that explains the FUNCTIONAL purspose of code/library. It should not include a technical breakdown as we end up with the same problem as with comments in code
So documentation should be

Explains Functional breakdown
Meaningful to the reader
The only exception here is that for libraries examples on using the library and examples on calling functions are often very helpful

I'm still working on improving my ability to write meaningful documentation for my work, especially for libraries I create.

Vandolf Estrellado • Jan 3 '22

Wow, thanks for the thorough feedback. I pretty much agree with you on all your points! I try to only write documentation that I feel is required. 100% of the time that is documentation about the input, output, and possible side effects. I only question if I overdo it sometimes =)

William Cairns • Jan 3 '22

If the function definition are the inputs - and the name of the function should make it clear what it returns :) So adding those is quite possibly more than is needed

If I have a function called
getUserDetails(id)

It should be clear to you that you send in a user id and will get a details object back. It doesnt need comments. As the coder using this function you should not need to know where the userDetails are coming from, if you did then the name should be improved. I use id to represent the primary key, this has become a norm within the team, so everyone would know what the id field should contain :)

Vandolf Estrellado • Jan 3 '22

Again, I 100% agree! For functions that are self-explanatory, there is no need for documentation =)

There is a special case where I disobey this rule. That is when it seems like it is self-explanatory but it actually isn't. When wrapping system-level databases that has its own set of rules that you have no control over, I write extensive documentation to ensure that consumers of the property/function are aware of those rules.

For example,

 /**
     * The name that should be used to display the (raw) contact. This is the unstructured component
     * of the name should be consistent with its structured representation.
     *
     * The [displayName] is the unstructured representation of the name. It is made up of structured
     * components; [prefix], [givenName], [middleName], [familyName], and [suffix].
     *
     * ## Insert/update operations
     *
     * You have three different options when inserting/updating a [NameEntity],
     *
     * 1. If the [displayName] is null and there are non-null structured components provided (e.g.
     *   [givenName] and [familyName]), the Contacts Provider will automatically set the
     *   [displayName] by combining the structured components.
     *
     * 2. If the [displayName] is not null and all structured components are null, the Contacts
     *   Provider automatically (to the best of its ability) sets the values for all the structured
     *   components.
     *
     * 3. If the [displayName] and structured components are not null, the Contacts Provider does
     *   nothing automatically.
     *
     * #### Important things to know about
     *
     * If your app only allows users to update the structured components and not the combined
     * [displayName], you should set the [displayName] to null when performing an update. This means
     * **option 1 is for you**. Otherwise, if you are trying to set all structured components to
     * null but you leave the [displayName] not null, the Contacts Provider will automatically set
     * the value(s) of the structured components to a derived value from the [displayName]. In
     * effect, your app would seemingly not allow users to clear the name.
     *
     * If your app only allows users to update the [displayName] and not the structured components,
     * you should set the structured components to null when performing an update. This means
     * **option 2 is for you**. Otherwise, if you are trying to set the [displayName] to null but
     * you leave the structured components not null, the Contacts Provider will automatically set
     * the value of the [displayName] to a combined value from the structured components. In effect,
     * your app would seemingly not allow users to clear the [displayName].
     *
     * If you want to manually update both the [displayName] and structured components with your own
     * custom algorithm, you may do so at your own discretion =)
     *
     * ## [ContactEntity.displayNamePrimary] vs [Name.displayName]
     *
     * The [ContactEntity.displayNamePrimary] may be different than [Name.displayName]. If a [Name]
     * in the Data table is not provided, then other kinds of data will be used as the Contact's
     * display name. For example, if an [Email] is provided but no [Name] then the display name will
     * be the email. When a [Name] is inserted, the Contacts Provider automatically updates the
     * [ContactEntity.displayNamePrimary].
     *
     * If data rows suitable to be a [ContactEntity.displayNamePrimary] are not available, it will
     * be null.
     *
     * Data suitable to be a Contacts row display name are;
     *
     * - [Organization]
     * - [Email]
     * - [Name]
     * - [Nickname]
     * - [Phone]
     *
     * The [ContactEntity.displayNamePrimary] is automatically resolved by the Contacts Provider. It
     * may not be manually modified.
     */
    val displayName: String?

Without the documentation above, I feel like users of this property will make mistakes and create bugs. Actually, the reason why I have so much documentation on this one property is because I encountered a head-scratching bug with it.

In any case, you are correct. There is no need for documentation on self-explanatory code.