Hi,
I really appreciate the work, time and effort you put into PFL.
I was just starting a new C/C++ project and was wondering what are the current best practices for organizing files. So I was looking into it when I found your research, proposed layout.
I read through The Pitchfork Layout (PFL) ideas, reddit post and Project Layout Survey Results and Updates.
I understand this to be the most popular, status-quo, currently established (but not necessarily best) practices.
I had some thoughts that wouldn’t let me rest, to not say something in good conscious.
So if you let me I’d like to share some constructive criticism:
Project Directory naming seems really inconsistent.
I understand that names came out as most popular vote in individual poll questions, and that might be the cause of inconsistency. The other reason is “We are already used to it” [this mess].
I have problem along 2 axes with lack of consistency: plurality and abbreviation.
-
Singular
build/
src/
include/
external/
-
Plural
tests/
examples/
extras/
data/
tools/
docs/
libs/
-
Abbreviated
-
Not abbreviated
build/
include/
tests/
examples/
external/
extras/
data/
tools/
Does this project only have one source but multiple docs, libs?
Please, this cannot be the proposed layout for new designs. (That we will have to live with for decades.)
There are others like source - header, compile - include pairs yet the proposal suggests using src (source) with include… but I’m gonna let linguists deal with that one…
I would be interested in a new poll voting between 4 consistent naming scheme, and another vote between the winner and the current inconsistent PFL (or a vote between the 5 – not sure if forcing people who would want the current layout to choose their least offending consistent layout would be beneficial or not - would need to ask a survey specialist for their opinion).
Singular Not abbreviated
Plural Not abbreviated
sources/
documentations/
libraries/
builds/
includes/
tests/
examples/
externals/
extras/
* or optionals/
, see later
data/
* It has Schrödinger’s plurality, it’s both or just don’t ask before it collapses ;)
tools/
Singular Abbreviated
src/
doc/
lib/
bld/
* would bil/
be better?
inc/
tst/
* tes/
? or are we good with test/
and it’s a 4 character limit
exa/
* xmp/
? or exam/
ext/
opt/
* here is where optional/
comes in instead of extra/
dat/
*
too/
* tol/
? tl/
? or keep 4 character tool/
here too?
Plural Abbreviated
srcs/
docs/
libs/
blds/
* would bils/
be better?
incs/
tsts/
* tess/
? or tests/
exas/
* xmps/
? or exams/
exts/
opts/
* here is where optionals/
comes in instead of extras/
data/
* or you can even have dats/
toos/
* tols/
? tls/
? or keep tools/
I think both SNA, PNA would be acceptable. I don’t think anyone would like full SA, PA.
I can live with if people are married to src and they don’t want to type a few extra characters because it’s so common but I do think it’s stupid. (I mean it’s stupid that they don’t want to change it because they are so used to it. Or that they have to type src and a tool doesn’t auto-completes it to source. Well, people were also used to slavery but over time they realized that it’s not right.. this is certainly less important, we’ll see if it gets into history books – “How security flaws in C codes ended the world” is more likely)
I’m also fine with lib abbreviation, but libs just don’t make any sense to me. It should be either srcs, libs, docs or src, lib, doc trio.
In the poll there were no singular lib
option (only libs, mods, and subdiv ...ew yuck), so I don’t know statistically how sound are these results. (plugins, modules were also not an option? also mods just sound to me like twitch moderators now, and libs like political liberals) That poll looks like a prime candidate for redoing. (But it doesn’t really matter to me, I’m not involved in large scale software development, I’m usually doing embedded firmware development. To me lib sounds like a folder containing any libraries used - internal or external, or maybe compiled library files that the project publishes for other project to use. So I’m clearly out of my depth here. Though to me it sounds a bit confusing. Modules, parts, components might sounds more intuitive IMO than lib, but people who work on these daily probably have better ideas.)
I don’t like using both external and extras names because they sound so similar (or abbreviate to the same 3 letter).
Just to be clear:
external/
is any external dependency (which can something you wget or git submodules...)
extras/
is a submodule root (but not git submodule, because that goes into external) (and it’s the optional submodules, not the mandatory ones)
- and
libs/
is where the mandatory submodules are ...if the project is divided into submodules (but again not git submodules, because that’s different)
Can anyone else besides me see why this terminology could be confusing?
I understand that you didn’t want to shoot yourself in the foot by calling them modules or packages because that would be confusing… so you shot your other leg instead ;)
I don’t know if component(s) would do or if that also used for describing something else.
As alternative I would suggest sub-project (instead of submodule which can describe another external dependencies aka projects). We are describing project layouts, if a project is divided into smaller parts/projects those could rightly be called sub-projects, no?
I think calling it package would be less confusing than submodule but not right.
Calling them modules is not great either but is submodule any better? If it’s a submodule what’s a module? Oh right a completely different thing a C++ module. Does that make any sense?
Do C++ modules go into module(s) directory? No? Why?
If we are not using modules directory (to publish C++ modules) then we could use it to hold sub-projects/project parts/project-modules (in contrast to C++ modules) … but shouldn’t!
Looking at the proposed submodule directory structure, these seem like full blown projects (with a common build/ system, external/ dependencies and tools/ ), they aren’t even really sub-projects. (But they are strongly coupled, maybe depend on each other… so they go into the same repo.)
So it’s a repository with many projects. No? Why aren’t we calling these submodules just projects?
Maybe our problem is that we are describing PFL as a project layout, when we should be describing it as a repository layout.
If a repository contains many projects, then why aren’t we calling it … just a repository. We can call it a many-project repository to differentiate it from a single project repository… or we can just borrow Visual Studio’s terminology and call it a “solution”. A solution contains one or more than one projects. Is this not what we are talking about here?
Will repositories hold more than one PFL Projects? Clearly a project can depend on other git submodules.
By the way thanks git for calling them submodules and not subrepos!
So PFL describes a repository and its subrepo dependencies, right? (And those dependencies should also follow PFL)
So PFL should apply to the whole repository, or can multiple PFL live in sub-directories of a repository?
Depending on that we can call PFL a repository layout instead of project layout, or call it a solution layout (which can have many inter dependent projects).
Am I right that a (multi VS project) VS solution can be a PFL project where the solution’s projects live in the submodule root directory but the solution cannot be PFL submodule … doesn’t seem like the directory structures would work out. Or can PFL submodules be nested and divided further?
Anyway, I think external/
directory name is fine for dependencies (I know deps
is not good, so neither is dep
, maybe req/
could be an alternative as in requirements, required dependencies), but for multi project solutions libs and extras doesn’t seem great. External and extras sounds more closly related than libs and extras. Wouldn’t required/
and optional/
be better? Should they even be top level directories or 2 sub-directories of modules
or projects
or parts
or whatever (maybe it’s a solution name, maybe it stays libs
or lib
I don’t know).
Well I hope that some of this helps someone somewhere at some point.
TLDR:
I think this is the most abbreviated I would ever go for
src/
doc/
lib/
build/
inc/
test/
example/
ext/
opt/
dat/
tool/
And any build system that worth its weight in salt should handle the optional plural s
ending(s)
and any mix between these abbreviations and full non abbreviated folder/directory names:
source/
documentation/
library/
(I would rename/move this if its purpose is to hold many inter related projects)
build/
include/
test/
example/
external/
optional/
data/
tool/
Because until we can agree on a consistent naming method people will mix and match to their heart desire.