From f1bc15bf4faf084071e641fa7944b418ee6495cd Mon Sep 17 00:00:00 2001 From: Victor Woeltjen Date: Fri, 14 Aug 2015 12:18:53 -0700 Subject: [PATCH] [API] Begin adding notes for API redesign --- docs/src/design/index.md | 3 + docs/src/design/proposals/APIRedesign.md | 233 +++++++++++++++++++++++ 2 files changed, 236 insertions(+) create mode 100644 docs/src/design/index.md create mode 100644 docs/src/design/proposals/APIRedesign.md diff --git a/docs/src/design/index.md b/docs/src/design/index.md new file mode 100644 index 0000000000..7b4c3e4ebf --- /dev/null +++ b/docs/src/design/index.md @@ -0,0 +1,3 @@ +Design proposals: + +* [API Redesign](proposals/APIRedesign.md) \ No newline at end of file diff --git a/docs/src/design/proposals/APIRedesign.md b/docs/src/design/proposals/APIRedesign.md new file mode 100644 index 0000000000..f1bf359cec --- /dev/null +++ b/docs/src/design/proposals/APIRedesign.md @@ -0,0 +1,233 @@ +# Overview + +The purpose of this document is to review feedback on Open MCT Web's +current API and propose improvements to the API, particularly for a +1.0.0 release. + +Strategically, this is handled by: + +* Identifying broader goals. +* Documenting feedback and related background information. +* Reviewing feedback to identify trends and useful features. + * In particular, pull out "pain points" to attempt to address, + as well as positive attributes to attempt to preserve. +* Proposing a set of API changes to address these "pain points." + * This also takes into account scheduling concerns. +* Once agreed-upon, formalize this set of changes (e.g. as UML + diagrams) and plan to implement them. + +# Goals + +## Characteristics of a good API + +A good API: + +* Is easy to understand. +* Rewards doing things "the right way." +* Saves development effort. +* Is powerful enough to support a broad range of applications. + +These characteristics can sometimes be at odds with each other, or +with other concerns. These should typically be viewed as participants +in trades. + +## Evaluating APIs + +APIs may be evaluated based on: + +* Number of interfaces. + * How many application-specific interfaces do I need to know to + solve a certain class of problems? +* Size of interfaces. + * How many methods does each interface have? +* Depth of interfaces. + * Specifically, how many methods do I need to call before the return + value is of a form that is not specific to the API? +* Clarity of interfaces. + * How much documentation or learning is required before an interface is + useful? +* Consistency of interfaces. + * How similar is one interface to an analogous interface? +* Utility of interfaces. + * How much development effort is reduced by utilizing these interfaces, + versus accomplishing the same goals with other tools? +* Power of interfaces. + * How much application functionality can I influence with the interfaces + that are available to me? + +In general, prefer to have a small number of simple, shallow, clear, +useful, powerful interfaces. + +# Developer Feedback + +## Developer Intern Feedback + +This feedback comes from interns who worked closely with +Open MCT Web as their primary task over the Summer of 2015. + +* Initially, it was confusing that many things in files that are in + very different locations in the code base refer to each other. + * Perhaps explain more the organization strategy behind the + different main sections, like "commonUI" vs "core". +* This may be just me, but there are often long chains of related + functions calling each other, and when I had to modify the behavior, + I had a hard time remembering to look for the highest level function + in the call chain to change. I also sometimes had a hard time finding + the connections between the functions. But, that is important because + the implementation of the functions along the chain may change later. +* One very helpful thing that you could add might just be documentation + that is not in paragraph format like in the current developer guide. + I would just like a list of all the functions and members of each kind + of object there is, and descriptions of what they are and how they're + used. + * Also, the current developer guide pdf's words that are in 'code font', + rather than the normal text, are not searchable. + (Depending on the pdf viewer.) +* I do appreciate that there is some example code. +* I am still slightly confused about what "domainObject" refers to in + different situations. +* The tutorials are helpful, but only really for designing new views. + It doesn't help much with gaining understanding of how the other parts + of the application work. +* The general idea of 'telemetry' in this context is kind of confusing. + It is hard to figure out what the difference between the various ways of + dealing with telemetry are. e.g., what is the difference between just + "Telemetry" and the "Telemetry Service"? There are many + "Telemetry Thing"s which seem related, but in an unclear way. + +## Plugin Developer Feedback + +This feedback comes from developers who have worked on plugins for +Open MCT Web, but have not worked on the platform. + +* Not a lot of time to work on this, made it hard to get up the learning + curve. + * Note that this is the norm, particularly for GDS development. + +## Misc. Feedback (mostly verbal) + +* Easy to add things. +* Separation of concerns is unclear (particularly: "where's the MVC?") +* Telemetry API is confusing. In particular, `TelemetrySeries` should + just be an array. + * Came out of design discussions for Limits. +* Capabilities are confusing. + +## Victor's Notes + +* Bundle mechanism allows for grouping related components across concerns, + and adding and removing these easily. (e.g. model and view components of + Edit mode are all grouped together in the Edit bundle.) + +## AngularJS + +Angular 2.0.0 is coming (maybe by end of 2015.) + +It will not be backwards-compatible with Angular 1.x. +The differences are significant enough that switching to +Angular 2 will require only slightly less effort than switching +to an entirely different framework. + +We can expect AngularJS 1.x to reach end-of-life reasonably soon thereafter. + +Our API is currently a superset of Angular's API, so this directly effects +our API. Specifically, API changes should be oriented towards removing +or reducing the Angular dependency. + +### Angular's Role + +Angular is Open MCT Web's: + +* Dependency injection framework. +* Template rendering. +* DOM interactions. +* Services library. +* Form validator. +* Routing. + +This is the problem with frameworks: They become a single point of +failure for unrelated concerns. + +### Rationale for Adopting Angular + +The rationale for adopting AngularJS as a framework is +documented in https://trunk.arc.nasa.gov/jira/browse/WTD-208. +Summary of the expected benefits: + +* Establishes design patterns that are well-documented and + understood in industry. This can be beneficial in training + new staff, and lowers the documentation burden on the local + development team. If MCT-Web were to stay with its current + architecture, significant developer-oriented documentation + and training materials would need to be produced. +* The maintainability of MCT-Web would be enhanced by using a + framework like Angular. The local team would enjoy the benefits of + maintenance performed by the sponsor, but would not incur any cost + for this. This would include future upgrades, testing, and bug fixes. +* Replaces DOM-manipulation with a declarative data-binding syntax + which automatically updates views when the model data changes. This + pattern has the potential to save the development team from + time-consuming and difficult-to-debug DOM manipulation. +* Provides data binding to backend models. +* Provides patterns for form validation. +* Establishes documented patterns for add-on modules and services. +* Supports unit tests and system tests (tests which simulate user + interactions in the browser) +* Angular software releases can be expected to be tested, which would + allow MCT-Web developers to focus on MCT-specific features, instead + of the maintenance of custom infrastructure. + +## Actual Experience with Angular + +Most of the expected benefits of Angular have been invalidated +by experience: + +* Feedback from new developers is that Angular was a hindrance to + training, not a benefit. ("One more thing to learn.") Significant + documentation remains necessary for Open MCT Web. +* Expected enhancements to maintainability will be effectively + invalidated by an expected Angular end-of-life. +* Data binding and automatic view updates do save development effort, + but also carry a performance penalty. This can be solved, but requires + resorting to exactly the sort of DOM manipulations we want to avoid. + In some cases this can require more total development (writing a + poorly-performing Angular version, then "optimizing" by rewriting a + non-Angular version.) +* Expected reduction of test scope will also be invalidated by an + expected end-of-life. + +Other problems: + +* Hinders integrating non-Angular components. (Need to wrap with + Angular API, e.g. as directives, which may be non-trivial.) +* Interferes with debugging by swallowing or obscuring exceptions. + +# Feedback Review + +## Problem Summary + +The following attributes of the current API are undesirable: + +[ ] It is difficult to tell "where things are" in the code base. +[ ] It is difficult to see how objects are passed around at run-time. +[ ] Multiple interfaces for related concepts (e.g. telemetry) is confusing. +[ ] API documentation is missing or not well-formatted for use. +[ ] High-level separation of concerns is not made clear. +[ ] Interface depth of telemetry API is excessive (esp. `TelemetrySeries`) +[ ] Capabilities as a concept lack clarity. +[ ] Too many interfaces and concepts to learn. + +## Positive Features + +It is desirable to retain the following features in an API redesign: + +[ ] Creating new features and implementing them additively is well-supported. +[ ] Easy to add/remove features which involve multiple concerns. + +## Requirements + +The following are considered "must-haves" of any complete API +redesign: + +[ ] Don't require usage of Angular API. +[ ] Don't require support for Angular API. \ No newline at end of file