Page 1 of 1
Library directory structure
Posted: Thu May 20, 2010 8:20 pm
by allspiritseve
Are there any common patterns for organizing directories for a library? It's always useful when a library has PEAR/Zend style naming that works well with an autoloader, but where should tests and documentation for the library go? Should they be outside of the namespace directory or inside?
Re: Library directory structure
Posted: Fri May 21, 2010 12:56 am
by Zyxist
I've been developing some PHP libraries and I use the following directory structure:
/docs - the documentation
/examples - examples
/lib - library source code
/tests - unit tests
/tools - various other tools, if needed
It is good to separate everything from the primary code, because if you would like to deploy the library in your application, you were interested with the library source code only, but not for example unit tests. And yes, I have a separate "namespace" for unit tests.
Re: Library directory structure
Posted: Fri May 21, 2010 9:02 am
by alex.barylski
I personally say test, docs, etc should be kept out of the library. When I download a lib I just want the code not all the cruft. Maybe thats just me.
Re: Library directory structure
Posted: Fri May 21, 2010 10:11 am
by allspiritseve
I agree-- but at the same time, that means the tests and docs aren't available for you to use when you need them. I suppose you can always copy the necessary files into different directories but that seems like it's more hassle than it should be.
Re: Library directory structure
Posted: Mon May 24, 2010 4:58 pm
by Bruno De Barros
@allspiritsteve, why would you need tests and docs when you're trying to use the code in your application? And especially when you're deploying it, there's no need for them.
I like Zyxist's approach, it's simple and keeps the right things appropriately separated.
Re: Library directory structure
Posted: Mon May 24, 2010 5:36 pm
by Christopher
allspiritseve wrote:I agree-- but at the same time, that means the tests and docs aren't available for you to use when you need them. I suppose you can always copy the necessary files into different directories but that seems like it's more hassle than it should be.
The question I have is what "when you need them" means. It seems like documentation goes with the developer, not the deployment. And for common kinds of docs, such as HTML or OS help files, they could not go with the code because it is not readily accessible on the server. Tests are similar because the test suite may not be installed on the system on which the app is running.
Re: Library directory structure
Posted: Wed May 26, 2010 9:40 pm
by josh
I keep tests in the same [sub]directory as the files those tests are testing. When do I work on just the production code without changing a test or vice versa? Hardly ever. Therefore I keep them together, since that's the way I use them. A phing task strips out the tests based on a file name pattern during deployment (optional).
Re: Library directory structure
Posted: Thu May 27, 2010 3:35 pm
by allspiritseve
Christopher wrote:allspiritseve wrote:I agree-- but at the same time, that means the tests and docs aren't available for you to use when you need them. I suppose you can always copy the necessary files into different directories but that seems like it's more hassle than it should be.
The question I have is what "when you need them" means. It seems like documentation goes with the developer, not the deployment. And for common kinds of docs, such as HTML or OS help files, they could not go with the code because it is not readily accessible on the server. Tests are similar because the test suite may not be installed on the system on which the app is running.
Documentation needs to be available so when I'm using a library I can refer back to it-- if I place the library in a /lib folder that can be autoloaded, there's not really a good place to put the documentation. I suppose I could create a /docs folder and place each library's docs inside that folder, but it seems stupid to have to place files in several different folders every time I install a new library. Placing the whole library into one folder with everything included would be the simplest solution.
Re: Library directory structure
Posted: Thu May 27, 2010 4:47 pm
by Christopher
allspiritseve wrote:Documentation needs to be available so when I'm using a library I can refer back to it-- if I place the library in a /lib folder that can be autoloaded, there's not really a good place to put the documentation. I suppose I could create a /docs folder and place each library's docs inside that folder, but it seems stupid to have to place files in several different folders every time I install a new library. Placing the whole library into one folder with everything included would be the simplest solution.
Agreed, but my point was that "when I'm using a library" usually does not refer to when the server where the app is deployed -- unless you are editing directly on the live server. I think keeping things together on your development server makes sense, and is an interesting point.
Re: Library directory structure
Posted: Fri May 28, 2010 1:19 am
by Zyxist
If the documentation is kept separately, it can be still deployed on the server when someone needs it. If it is kept together, it is hard to cut it off when it is not needed. The same with unit tests. Josh must use dedicated Phing tasks to cut off tests, I don't need any tool.
Furthermore, the documentation and tests do not need to reflect the code structure perfectly. For example, in one of my libraries, the documentation consists of nearly 370 HTML files, whereas there are only 52 PHP files. PHPDoc cannot cover all the cases, because it is just an API doc, and a good library needs a user guide. Sometimes, there are some features that do not match PHPDoc, and they must be documented separately, too (i.e. file formats). The same with tests - in the newer version I have a group of tests that check the backward compatibility; they often cover the same cases as the normal tests, but in the different environment and with different settings, so I have actually two groups of different tests for the same things.