Guy who write the code usually don't have enough distance (and often not enough skill where, documenting is an animal in its own right!) to document the same.
I encourage devs to ask questions, and document code they come across when they don't get it (hopefully, after they figure it out). This means that, the meandering effort you refer, of figuring what it really does... Somebody, in my experience, have to do this at least once.
Most, "horse did, horse mouth documented" code I come across - the docs in there paraphrase the code - dead weight which I promptly delete in a separate commit (sneering is not productive, removing dead weight is)
Good comments often signal bad code. Guy suddenly realized some danger with their code, wrote a comment and moved on cause no time to fix. Which is perfectly fine. They save somebody else the trouble of falling into a trap, and boost the confidence of the time-endowed person who are going to fix the code, and delete the signpost.
I'd much rather a // bad code comment than nothing - because I respect my co-workers. If something looks twisted and isn't labeled bad/clumsy I'll assume its crooked for a reason, whereas sometimes it's not.
Part of being an API designer (and much code isn't "API" just grease) is having a knack for roleplaying as a beginner, and adopt the TLDR mentality of somebody who need to understand something, but are lacking the time and dedication to do verbose let alone code.
Not all code that needs documenting is bad, but writing code that people just get without much effort (and if possible reading signatures NOT the code) is a good smell.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Guy who write the code usually don't have enough distance (and often not enough skill where, documenting is an animal in its own right!) to document the same.
I encourage devs to ask questions, and document code they come across when they don't get it (hopefully, after they figure it out). This means that, the meandering effort you refer, of figuring what it really does... Somebody, in my experience, have to do this at least once.
Most, "horse did, horse mouth documented" code I come across - the docs in there paraphrase the code - dead weight which I promptly delete in a separate commit (sneering is not productive, removing dead weight is)
Good comments often signal bad code. Guy suddenly realized some danger with their code, wrote a comment and moved on cause no time to fix. Which is perfectly fine. They save somebody else the trouble of falling into a trap, and boost the confidence of the time-endowed person who are going to fix the code, and delete the signpost.
I'd much rather a
// bad codecomment than nothing - because I respect my co-workers. If something looks twisted and isn't labeled bad/clumsy I'll assume its crooked for a reason, whereas sometimes it's not.Part of being an API designer (and much code isn't "API" just grease) is having a knack for roleplaying as a beginner, and adopt the TLDR mentality of somebody who need to understand something, but are lacking the time and dedication to do verbose let alone code.
Not all code that needs documenting is bad, but writing code that people just get without much effort (and if possible reading signatures NOT the code) is a good smell.