Tweaked the README file a bit more.

This commit is contained in:
Javier Cicchelli 2022-12-20 02:49:26 +01:00
parent 5aeec04e19
commit 9682a78f80

View File

@ -4,7 +4,7 @@ The _"My Files"_ application was created as a result of the requirements defined
## App
In a nutshell, the purpose of this application is to manage a remote file system accessible through the Internet via a provided REST API endpoint.
In a nutshell, the purpose of this application is to manage a remote file system accessible throught the Internet via a provided REST API endpoint.
In its current state, the application allows its users to:
@ -27,13 +27,13 @@ In its current state, the application allows its users to:
## Implementation
This application was built as a `SwiftUI` application as the kind of app this assignment defined actually fits the use case to use this young framework, even though `UIKit` has been battle-tested for more than a decade now. The declarative nature of the framework, which is based in describing the behaviour of the UI interface, and no by implementing how it should work (like with the imperative approach we were used to), allows the developer for simpler, more maintainable codebases. Of course, the bridge support to native UI framework, like `UIKit` or `AppKit`, is also available for those cases when the developer needs to build tailored UI components and/or more fine-grained control over UI controls. Finally, another advantage worth mentioning, but given the scope of this assignment, is not really relevant is the possibility of porting the app to other platforms, like iPad, Mac, Apple TV, Apple Watch or even CarPlay easily, as the framework implements an encapsulation (or better said, an erasure...) through its APIs of several `UIKit`, `AppKit`, and `WatchKit` components that developer usually need to build their apps.
This application was built as a `SwiftUI` application as the kind of app this assignment defined actually fits the use case to use this young framework, even though `UIKit` has been battle-tested for more than a decade now. The declarative nature of the framework, which is based in describing the behavior of the UI interface, and no by implementing how it should work (like with the imperative approach we were used to), allows the developer for simpler, more maintenable codebases. Of course, the bridge support to native UI framework, like `UIKit` or `AppKit`, is also available for those cases when the developer needs to build tailored UI components and/or more fine-grained control over UI controls. Finally, another advantage worth mentioning, but given the scope of this assignment, is not really relevant is the possibility of porting the app to other platforms, like iPad, Mac, Apple TV, Apple Watch or even Carplay easily, as the framework implementes an encapsulation (or better said, an erasure...) through its APIs of several `UIKit`, `AppKit`, and `WatchKit` components that developer usually need to build their apps.
With choosing the `SwiftUI` framework to build this app, it also comes the question of the type of architecture to use with it. Arguably, my preferred answer to this particular question is **"None"**. Given this framework is highly opinionated (much more opinionated than the view controllers from `UIKit` or `Appkit`), and that it is supported by the power and capabilities that the Swift language itself provides, this framework has lots of extra, helpful features that a SwiftUI `View` can use out of the box (like the `@State`, `@Binding`, `@AppStorage` and `@FetchRequest` property wrappers), I would rather prefer to fully understand how SwiftUI works and use some appropriate, useful design patterns instead. Given my experience, it is preferable to just go with the flow of the technology you use, because the less time spent swimming against the current (or fighting against your framework of choice), the more time developers have to actually solve the problems that actually matter to their apps and, of course, their users.
Now that design patterns have been mentioned, in this exercise some well-known patterns are being used in some degree. For example, the *Singleton* pattern is used to initialise the container in the `DependencyInjection` core library. Both public and internal *Interfaces* that either describe an object or how it should behave are used throughout this codebase, as this pattern is essential to plug the libraries into the modules, and the modules into the actual app and, as a consequence, for testability purposes as developer can easily create mocks, stubs and spies out of them. Then the *Adapter* pattern is used to transform some object into another object like, for example, when transforming some data from a business model instance to a model used exclusively by a UI component or view. Last, but definitely not least, the *Use cases* are a pattern from Android that basically execute a function based on some given input, and provides an output after that particular function is finished. This pattern is particularly useful to encapsulate the logic that a view needs to execute in a simple way, without the need to create view model classes that inherit from the `ObservableObject` class.
This application was built with scalability in terms of the codebase in mind, which tries to address how this codebase could grow in a controllable, organised manner. For this very reason, this application uses the Swift Package Manager (or simply `SPM`) to define the `Cores`, `Libraries` and `Modules` packages. Inside each package, there are targets that encapsulate a some certain functionality or feature with its respective assets inside. Of course, some of these targets also have related test targets that contain test cases with some relevant unit tests. The application takes a bottom-up approach, as the App could use `Cores`, `Libraries` and `Modules` targets but the Modules could use only `Cores` and `Libraries` targets; Libraries could use only `Cores` targets and 3rd party dependencies; and Cores could use only 3rd party dependencies if needed. This approach forces the developer to think about actual separation of concerns, as the different features and dependencies should be grouped as independent, reusable building blocks, and to move the code into the SPM packages out of the main app target, reducing compiling time and overal weight of the application.
This application was built with scalability in terms of the codebase in mind, which tries to address how this codebase could grow in a controllable, organised manner. For this very reason, this application uses the Swift Package Manager (or simply `SPM`) to define the `Cores`, `Libraries` and `Modules` packages. Inside each package, there are targets that encapsulate a some certain functionality or feature with its respective assets inside. Of course, some of these targets also have related test targets that contain test cases with some relevant unit tests. The application takes a bottom-up approach, as the App could use `Cores`, `Libraries` and `Modules` targets but the Modules could use only `Cores` and `Libraries` targets; Libraries could use only `Cores` targets and 3rd party dependencies; and Cores could use only 3rd party dependencies if needed. This approach forces the deveeloper to think about actual separation of concerns, as the different features and dependencies should be grouped as independent, reusable building blocks, and to move the code into the SPM packages out of the main app target, reducing compiling time and overal weight of the application. The only drawback I have encountered with this approach is that the Xcode previews for those views that implemented previews don't work in the current Xcode version.
## TODO
@ -45,7 +45,10 @@ Currently, the work that has been left outside of this assignment
- [ ] Move duplicated code from Modules to sensible, common Libraries dependencies;
- [ ] Add support for new APIs introduced on iOS 16 (especially for navigation);
- [ ] Improve communication between the public views on the Modules and the core application;
- [ ] Write further documentation, especially for the public interfaces;
- [ ] Implement API response caching to optimise the use of the network connection;
- [ ] Implement an offline mode with a synchronisation mechanism to keep the device and remote file systems in sync;
- [ ] Write further inline documentation, especially for the public interfaces;
- [ ] Write further `DocC` documentation and articles for the libraries, modules and app;
- [ ] Write more unit tests with the `XCTest` framework for all the relevant logic code distributed in the Core, Library and Modules dependencies;
- [ ] Write UI tests for happy and error paths with the `XCUITest` framework;
- [ ] Set Xcode plugin that uses the `SwiftFormat` library to lint and format the source code on development delivery pipeline;