
Why do software engineers put off writing documentation comments? - Austin_Conlon
https://www.quora.com/Why-do-software-engineers-put-off-writing-documentation-comments?share=1
======
BossingAround
For me, this feels more like a problem of mindset. I'd talk to one of my
fellow developer and after giving him feedback that this 500-line bash script
desperately needs to be broken up into functions, he replied: "of course,
we'll do that when there's time". The problem is, there's never time.

Documentation is best written right when you finish writing the code and
you're happy with it. At the very least, I'd recommend writing comments which
will make the author remember the most important things that need to be
documented.

Lack of docs, or 'we'll refactor it later' code has also become my #1 reason
for refusing to merge. I'd allow it if and only if the deadline is today, and
it's Friday at 3pm.

It's also true though that a lot of my fellow developers were just utterly bad
at writing documentation. If I saw an attempt, though, I'd merge and fix the
docs later (or pester them about fixing it later).

------
warmfuzzykitten
The biggest reason is probably that no one who matters to their careers will
criticize them for not writing comments. That goes double for documentation
outside comments, which they know from experience no one will read, anyway.

------
SamReidHughes
When writing code, you don't want to context switch to writing doc comments
while holding the problem in your head. So you do it after the fact, if at
all.

~~~
chillacy
I’ve switched to writing my docs first when writing libraries. it’s like a
play on test driven development. The benefit is that I start with a sane and
interface if the first thing i think about is the user and not the
implementation.

------
nunez
bc cms's generally have terrible wysiwyg editors and devs would rather be
coding.

