Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Pipeless API
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple API
Learn More
-
If people are overwhelmed/intimidated by your comments, it probably means that the language you're using is too technical for them, so they are confused about what exactly it is that you expect of them. I suggest you communicate with the assumption that the reader has no clue what on earth you're talking about, but also keep it short and simple. Don't know if this answers your question.
-
@aadilp exactly this.
The limit of "too much documentation" is high enough for you not to worry about. But you have to make sure, that the language is understandable for people who have no idea about your code base. And yet describe the specifics, for example when a function throws errors and such stuff. -
Assuming these are code comments in situ:
Do your comments describe what the code is doing, or does it prescribe what the intended and ideal outcome is?
It’s been my experience that comments trying to do the former (that’s what the code itself and a Readme or Wiki document are for) ends up overly lengthy at the expense of quickly, but clearly delivering on the latter.
If you find yourself writing an especially long comment to explain a chunk of code and its functionality, consider instead a brief explanation of what you expect to return and include a link to said Readme or Wiki.
Related Rants
every single fuckening day
How documentation works
Apologies if this has been asked here before, but I wanted an open feedback on a query: Is there such a thing as overdocumenting?
I take pride in being a very articulate developer, being as descriptive as possible in my emails, internal communications, PR review comments, JIRA etc.
A product guy from the company today mentioned: "Though I understand your good intent behind being as descriptive as possible, it is possible that some of the junior engineers might get overwhelmed/ intimidated looking at those comments/ emails and it might stop them reaching out to you with your doubts."
I was not able to wrap my head around this, because I don't understand how a descriptive explanation might overwhelm anyone. It's a skill I picked up going through my career and I personally have always respected peers who documented things properly.
Open to feedback. Thank you in advance.
question
documentation