Doc blocks are mandatory, imho, but also a separate topic. The problem is that a lot of developers use the existence of docblocks and code comments as an excuse to not have to do non-code documentation.
I argue, in the post, that non-code documentation is also important, because it fills a different role than in-code documentation. Ideally you would have both!
I'm quite undecided. On most projects that had architecture docs, I was the person to write them. I never referred to them again, nor did anybody else.
I can see them being helpful should I disappear from a project, but I'm not convinced they are essential. They also take time, which is time not spent doing something else.
That's fair, I'd say it depends somewhat on the project. But also, fixing the knowledge silo is, long term, a thing worth doing for the project. That's an extra point I could add to the subject, thanks for that :)
Couldn't agree more, the risk of refactored code linked to legacy comments is too high.
Always believed a summary doc block along with well named variables/method names should provide enough guidance for very little additional effort.
Although coming up with well named variables is another challenge in itself.
Doc blocks are mandatory, imho, but also a separate topic. The problem is that a lot of developers use the existence of docblocks and code comments as an excuse to not have to do non-code documentation.
I argue, in the post, that non-code documentation is also important, because it fills a different role than in-code documentation. Ideally you would have both!
I'm quite undecided. On most projects that had architecture docs, I was the person to write them. I never referred to them again, nor did anybody else.
I can see them being helpful should I disappear from a project, but I'm not convinced they are essential. They also take time, which is time not spent doing something else.
That's fair, I'd say it depends somewhat on the project. But also, fixing the knowledge silo is, long term, a thing worth doing for the project. That's an extra point I could add to the subject, thanks for that :)
Found the problem! Hehe ;)