search

vector-of-bool / pitchfork

Pitchfork is a Set of C++ Project Conventions
MIT License
1.12k stars 56 forks source link

Directory naming inconsistency #47

Open szikra opened 1 year ago

szikra commented 1 year ago

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.

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

Singular Abbreviated

Plural Abbreviated

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:

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

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:

Because until we can agree on a consistent naming method people will mix and match to their heart desire.

szikra commented 1 year ago

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 commented 10 months ago

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 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:

and you should just use what complies with the above