Directory naming inconsistency

[szikra]

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

  • src/
  • docs/
  • libs/

• 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

• source/
• documentation/
• library/
• build/
• include/
• test/
• example/
• external/
• extra/ * or optional/, see later
• data/ * I mean I know data is plural form of Latin datum, but it’s a mass noun?… https://crosstalk.cell.com/blog/is-data-plural, https://www.britannica.com/dictionary/eb/qa/Is-Data-Singular-or-Plural-
• tool/

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.

[szikra]

In case typing speed or Carpal Tunnel Syndrome is a concern as a reason to use src instead of source or that people write src out of habit from muscle memory I think I can help...

; Here's an AutoHotkey script that replaces src with source as you type it:
:*:src::source

; And here are other abbreviations that are only auto-completed on pressing TAB key
; (to avoid accidentally replacing file extensions when typing foo.doc... and similar)
#Hotstring EndChars `t ; Only TAB is used as trigger
#Hotstring O ; omit TAB from the replaced text (allows continuing it, for example making it plural)
::inc::include
::doc::documentation
::lib::library
::ext::external
::opt::optional

[SiebrenW]

I think that it's more important to stick to a common naming convention in POSIX-like systems, like Debian.
If I ls my /usr/local directory you see:

• bin < contains binary executables
• etc < contains extras, like
• include < contains external headers
• lib < contains extra stuff, like Find.cmake files (I think it shoudn't, but okay) and library binaries (.so/.a files)
• src < the actual source code of binaries found in the bin and lib directories

bin and lib are typically the artifacts in the build directory, so that isn't something we need to concern ourselves with, but src and include are exactly what we're using here.

Here my stance is: what do people expect? I don't expect a source dir, I expect src, as I expect an include dir and not inc. Besides that it becomes more iffy.

Regarding plural/singular: there is only one source, which is a collection of source files. As with the include, that's what you include with -I in the compiler. It's not includes, it's only a single one. docs is not "the doc", they're multiple documents typically, as with examples, given you have more than one, it makes sense to say examples so people see it and expect multiple examples, one of which showing what the user needs.

So here's my takes with what's important in order:

• what has the least technical issues? (ie: prevent private headers from leaking, least amount of work to use, prevent name clashes, cross compatible with other architectures etc.)
• what do people expect? (src, include, doc/docs), everyone has different experiences of course, but look at other conventions with the least issues. (example SDL is notorious for include issues)
• what IS it? ("the" source, "the" examples, "a" doc or "the" docs, "the" tools)

and you should just use what complies with the above