back
5 comments
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).

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.
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.
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.
bc cms's generally have terrible wysiwyg editors and devs would rather be coding.