Revisit File Structure & Naming Conventions #3517
Description
Now that most of the infrastructure reworks are done I would want to have a look at naming conventions and how files are organized.
One of the main goals of 3.0 was and still is to flatten the file structure and make it more obvious what a file contains. This has been achieved to a certain degree but there is still a lot of room for improvement.
As an example, it isn't always clear based on file names what is inside the file because there is no indication if it is a service, manager, factory, action, transformer and so on. This is being worked around by creating more and more nested folders that hold files of specific types that don't really have a definition around them.
Angular (with all its flaws) has a pretty good file naming convention in their style guide at https://angular.io/guide/styleguide. They suffix files with types that specific definitions to them within the angular system. We could employ a similar convention by suffixing files with service, manager, factory, action, resource, pipe, queue to make it clear that specific files contain specific parts of the application and not just a random class or helper that doesn't really have any significance to it.
This would make it easier for us to signal to developers what things are what and it is clearly visible where to find things while reducing the nesting. Another benefit is that any IDE or editor can easily find those files as you can search for the type by suffix.
Most of our community and audience are younger developers or developers that haven't worked on larger projects so making it easier to see what is what and it having clear definitions should be a goal for us. Core is a framework for other developers to work with and build on so we need to think of it in that way and not as a standalone application.
Proposed Structure & Naming Conventions
*.provider.ts
This would be a file that manages the lifecycle of a service, see https://en.wikipedia.org/wiki/Service_locator_pattern.
*.service.ts
This would be a file that manages and exposes a service through a https://en.wikipedia.org/wiki/Service_layer_pattern.
*.manager.ts
This would be a file that is responsible for mediating how objects interact with each other, see https://en.wikipedia.org/wiki/Mediator_pattern.
*.factory.ts
This would be a file that is responsible for the creation of other entities, see https://en.wikipedia.org/wiki/Factory_method_pattern.
*.action.ts
This would be a file that contains logic that interacts with the triggers service of core-kernel. This logic is always in the form of an action that is associated with a trigger.
*.pipe.ts or *.stage.ts
This would be a file that contains logic that interacts with the pipeline service in core-kernel. This would always be a class that is an implementation of the stage contract.
*.queue.ts
This would be a file that contains logic that interacts with the queue service in core-kernel. This would always be an instance of a queue.
*.resource.ts
This would be a file that contains logic for transforming an object into a unified format. Think of it as something like an API or a Response transformer.
*.dto.ts
This would be a file that contains a class whose only job is to hold some data, see https://en.wikipedia.org/wiki/Data_transfer_object.
Unit Test Relocation
Part of this could also that we reorganize unit tests to be closer to their source like is common in C++, Rust or Go. This keeps the source and tests closer together and it becomes apparent what is missing tests.
peer-communicator.ts
peer-communicator.test.ts
peer-connector.ts
peer-connector.test.ts
peer-processor.ts
peer-processor.test.ts
peer-storage.ts
peer-storage.test.ts
peer-verifier.ts
peer-verifier.test.ts
peer.ts
peer.test.ts
This would only affect unit tests as we move them right beside their source file. This means that you are forced to only test code that is available inside the package and can't accidentally sidetrack and end up writing an integration test because you brought in things that are not available to the package or completely unrelated.