I feel strong opinions about this subject, I've seen the easiness and welcoming warmth that documented code gives to new people in the code base (and by new I don't mean people with no experience).
I use both, both prose and long and clear variable names that try to speak the intention. I can pick up the code rather easily but my experience is that people don't want to be reading code for the most part unless they absolutely have to.
So as a Python dev I felt that self documented code was the best... but after working in a totally unknown code base in a new language to me... not having prose documentation is hellish.
Do the right thing, try to make comments and variables as simple as possible but not any simpler and also keeping in mind that simplicity is hard and expensive to attain.
Hell sometimes prose and code don't even matter if people won't read either. At that point you even have to consider making video tutorials, talks, conferences, whatever you have to do just to get your point across.
Documentation is hard, but not because of the medium. Some people digest code, others prose, others talks, other classes and a mentor.
And our job is to consider every single one, that is if you want your code to survive.
I agree strongly, especially to the prose part. It's probably a thing of preference, but I just love it if I can jump through a codebase, gaining a good idea of what it does by only reading the comments and some really trivial lines of code.
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.
I feel strong opinions about this subject, I've seen the easiness and welcoming warmth that documented code gives to new people in the code base (and by new I don't mean people with no experience).
I use both, both prose and long and clear variable names that try to speak the intention. I can pick up the code rather easily but my experience is that people don't want to be reading code for the most part unless they absolutely have to.
So as a Python dev I felt that self documented code was the best... but after working in a totally unknown code base in a new language to me... not having prose documentation is hellish.
Do the right thing, try to make comments and variables as simple as possible but not any simpler and also keeping in mind that simplicity is hard and expensive to attain.
Hell sometimes prose and code don't even matter if people won't read either. At that point you even have to consider making video tutorials, talks, conferences, whatever you have to do just to get your point across.
Documentation is hard, but not because of the medium. Some people digest code, others prose, others talks, other classes and a mentor.
And our job is to consider every single one, that is if you want your code to survive.
I agree strongly, especially to the prose part. It's probably a thing of preference, but I just love it if I can jump through a codebase, gaining a good idea of what it does by only reading the comments and some really trivial lines of code.