How should I organize a general-purpose programming library's directory structure? [closed]

Question

I've been writing my own general-purpose PHP library for a while and I'm thinking about how to organize the directory structure, but I wanted to get people's ideas before I formalized the directory structure for the library.

Here is what I have so far: https://github.com/homer6/altumo/tree/master/source/php

I was thinking I could either do it "By Topic" or "By Category". So far, I can only think of one example that I like of the "By Category": Boost http://www.boost.org/doc/libs/1_46_1/?view=categorized

Also, Qt is organized by module, but I think it's a bit messy because everything is kinda stuffed into QtCore http://qt-project.org/doc/qt-5/qtmodules.html

Any ideas?

Thanks in advance.

UPDATE: I found a really great book that has shown me a number of great library design conventions to follow: http://www.apibook.com/blog/

UPDATE: I found an interesting article that mentions organization of code (http://highscalability.com/blog/2012/3/26/7-years-of-youtube-scalability-lessons-in-30-minutes.html). At the bottom, it says: "What is your code tree going to look like? He wants these words to describe it: simple, pragmatic, elegant, orthogonal, composable. This is an ideal, reality is a bit different."

Answer 1

First of all, the chosen structure is a compromise decision, that means that you'll have to deal and prioritize some aspects over others depending on your purpose. There are some grouping criterias you could follow, such as:

• Functional Cohesion, I think that should be the strongest one in your design. Classes/files/resources with the same or similar functionality should be together
• Component Hierarchy, Depending on the granularity level you choose, that means if you prefer fine-grained components vs coarse-grained, you would have more or less files/resources in one folder. This can be controlled using folder hierarchy and nesting.
• Change, Some files are more likely to be changed than others, you have to keep this in mind in order to provide a folder hierarchy depending on the probability to be modified.
• Extensibility, For a framework to be useful and adaptable to almost any scenario you have to provide the possibility to extend components and functions. Adding a folder for extensions (aka plugins) is a good idea.

There are lot of criterias you should use, but always keep in mind the KISS Principle. You can search for package management in books like The Unified Software Development Process (Ivar Jacobson et al.), I hope this could be helpful.

Answer 2

Since it is multi-purpose library devoted to solve versatile problems or provide interfaces for common features, it is better to have structure by subject which may be DataType/Technology/Language/Protocol etc. like so:

+ Http   - request   - response   + util     - status_codes + Html   - Validator   + Form     - UploadFile   + Tag + JavaScript   - JSON + Ajax + XML   - Reader   - Writer   - Parser + DataType   - Array   - Integer   - String   - Double   - Float   + util     - datatypes_cast_lib 

On top we have:

• Http which is a protocol so your Http.request would be an interface to perform Http request
• Html which is markup language, so Html.Form.UploadFile will provide developer with features to create upload file forms
• JavaScript which is programming language, so your Javascript.JSON would solve problems of conversions from JSON to Arrays maybe
• Ajax which is technology
• XML which is markup language
• DataType which is ... well, data type.

Notice, that status_codes remain under util in Http. Every sub-library can have its own util features like DataType lib may need datatype_cast_lib to know how to juggle with datatypes.

This way of library organization mostly resembles organzation of PECL

Good question, BTW! I asked the same question myself frequently. I've been organizing and reorganizing my directories structure for years. It really depends on project. I've adapted structure above corresponding to structure you've provided here.