4 ms·
> I feel like PHP documentation is very undervalued PHP is documentation done right because of the comments, essentially "Stack Overflow" for PHP before stacko
by labrador 4y ago
> I feel like PHP documentation is very undervalued
PHP is documentation done right because of the comments, essentially "Stack Overflow" for PHP before stackoverflow.com was a thing.
I've found an example of documentation done wrong recently with Microsoft .NET 6.0. Apparently, Microsoft has decided that code samples are no longer important
- psalminen 4y agoI've been migrating to Azure and their SDK documentation is next to nonexistent. The codebase is also uncommented and inconsistent. It's just been a dumpster fire.
- kyriakos 4y agoMicrosofts documentation is horrible. They churn out api after api and never document it correctly.
- wiennat 4y agoWhat's happen to MS these days? I remember the documents during .NET 2.x days were very good, well-organized and useful.
- djxfade 4y agoThis can go both ways. I have seen some very dangerous code examples in the comment section of the PHP docs.
- labrador 4y agoUsually followed by a comment that says don't do what the last comment said
- zelphirkalt 4y ago> PHP is documentation done right because of the comments, essentially "Stack Overflow" for PHP before stackoverflow.com was a thing. It's funny really, for a programming language to rely on comments made by random people, instead of having those aspects covered in the documentation itself. Shows a bit of lack of care. It seems half-assed as many things in the ecosystem seem. What happens, if they ever lose that database of comments? The whole world scratches their heads wondering how to use standard library functions? Ridiculous. I hope they have good backups. > I've found an example of documentation done wrong recently with Microsoft .NET 6.0. Apparently, Microsoft has decided that code samples are no longer important And for as long as important documentation resides in comments in PHP docs, the same can happen to PHP docs. Lets say they push out PHP 9 and some things change. Someone thinks "Ah those comments are not actually true any longer. Lets get rid of them." Bam, massive resource lost, because the knowledge has not been integrated into the documentation.
- labrador 4y agoHere's a sample of a user generated comment on array_map Assuming they backup the website, how's it going to get lost? https://www.php.net/manual/en/function.array-map.php#113886 https://www.php.net/manual/en/function.array-map.php#113886