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)
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
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
I'm still working on improving my ability to write meaningful documentation for my work, especially for libraries I create.
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 =)
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 :)
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,
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.
80 20 rule