You get to choose your battles - some sections of the code get to have verbose documentation (I consider types a sort of documentation). On the other hand, meaningless utility function #2421354 can remain typeless.
I do this with 80% of the functions, and skipping that waste of focus on those last 20% - the meaningless crap that is allowed to remain meaningless crap - is what keeps my productivity from plummeting into the abyss.
You only have so much focus - wasting it on things that don't matter is far worse than some might think.
And properly documented functions reduce the chance of difficult to trace bugs which plummet productivity when you spent two days tracking them down because someone accidentally returned a JSON string instead of the deserialzed result.
And that makes sense... in a large, dysfunctional company.
A small team where everyone talks to each other, and everyone actually tests their shit, and an accidental JSON string gets caught the moment whoever implemented it runs their test (manual or autoamted).
Or any medium size business which has a code base more than a few hundred files.
It's a completely unnecessary burden to have your team remember the inner workings of a project when there are perfectly serviceable tools to automate that process.
Coming back to a sub component of a large project after six months to add a feature is far less daunting (and easier to delegate) if the code is unambiguous about what it expects and what it produces.
The only reason to forego such simple code documentation standards is if you're gunning for job security by way of noone else being able to understand what anything does.
As I said, not having overly verbose documentation doesn't mean having no documentation at all. If you have a module, its intent should be documented to begin with, as should any functions which aren't trivial / self-documenting.
When you're missing is that you don't need to document every sortArray function in order to have meaningful documentation.
2
u/IOFrame 2d ago
Nah, this is what makes PHP great.
You get to choose your battles - some sections of the code get to have verbose documentation (I consider types a sort of documentation). On the other hand, meaningless utility function #2421354 can remain typeless.
PHP doesn't have to be a bloated mess like Java.