Docs Not Included

 

Fig 1. Some Docs

One of the best assets we have is the extensive user land documentation for PHP. The documentation is maintained by several teams of developers working on one or more translations of the raw docbook format: A huge amount of effort is expended on the maintenance of user land documentation.

Unfortunately, the source code of PHP is not documented in the same way, in fact, it's barely documented at all.

The topic of how to get started as a beginner comes up rather a lot. 

The best answer depends on your experience; If you are already a confident C programmer, you're not going to need that much help, a good source search tool and a little bit of research and you're probably going to be able to do what you wanted to do without any help.

Those less experienced, typically PHP-first C-last programmers, less confident, or more friendly people looking to do something with PHP should find someone to mentor or help them. 

If you show up in room 11 on stackoverflow and wait five minutes, someone from internals will be along shortly on almost any day of the week.

That's bizarre, why don't you document PHP internals ?

The fact is that by the time you are in a position to document anything, you are far more useful doing other things than you are wasting your time writing documentation for people that will soon be able to write documentation (or not) for themselves.

In addition, complete documentation for internals is a never-ending task and constantly moving target: We try to make the most out of our chances to break ABI, there's almost a constant stream of work going on in some areas - for example, at the moment the JIT, a few weeks ago Fibers.

There is one pretty good attempt at internals documentation on Internals Book, but it took a team of people to put it together and it's perpetually out of date.

This means that code is de facto documentation for PHP, we don't put effort into documenting PHP because we are working on the code, and don't and won't have resources to do anything else; Anything you need to find out is to be found by understanding code. If you can't understand, come and get some help.

I recently expressed this in a chat room to someone who I personally spent many many hours trying to help, only for them to say this in public:

Which is honestly a chicken-shit, cowardly, irresponsible, immature response. Code that isn't documented is bad code. Period. Good naming and such is *part* of documentation, but it is not all of documentation.

When I tried to defend the position that documentation is code for PHP, my response was voted down.

I'm not saying that this is an ideal situation to be in, but it is in fact the situation we are in. 

I don't view it as a huge problem either: Those people that don't need comments every few lines in source to find their way around are not going to be helped by littering source code with information already contained in implementation. Those people that feel like they would be helped by such information are likely to still need someone to hold their hand while they're learning, and we're more than willing to do that hand holding.

While we don't have the resources to document internals, very many of us make ourselves available to help newbies, this we do have the resources for, even if nobody is being paid to make themselves available.

People > Docs

In any case, people are much better than docs. 

Documentation cannot reword itself, explain itself, it can't correct inevitable explanatory mistakes, show examples, tell you about history, or do anything that will really help you to understand if reading the code itself doesn't help you to understand.

That's all I have to say about that right now ...

Peace out phomies :)