3 ms·
Why do software engineers put off writing documentation comments?
- BossingAround 8y agoFor 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).
- nunez 8y agobc cms's generally have terrible wysiwyg editors and devs would rather be coding.
- SamReidHughes 8y agoWhen 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 8y agoI’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.
- smelly-code 8y agofunctional programming eradicates the concept of commented-out text used as documentation the idea is that if you have to explain the code then that makes it smelly
- warmfuzzykitten 8y agoThe 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.