In this talk you will learn about some of the approaches that you can take to effectively design and build native frameworks that behave consistently across platforms while leveraging each platform's native strengths and APIs. We'll go over the process all the way from designing a feature, to writing a feature specification, to a passing test suite for every platform.

1. Donny Wals // July 2020
Efficiently developing native
frameworks for multiple
platforms

2. 👋

3. 👋
• Blog: https://www.donnywals.com
• Book: https://practicalcombine.com
• Twitter: @donnywals
Donny Wals
iOS Engineer

4. Our SDK powers several apps and
provides networking capabilities
amongst other features.

5. SDKSDKSDKSDK

6. SDK
iPhone
Android
Web
Gaming
consoles
SDKSDKSDK

7. SDK
iPhone
Android
Web
Gaming
consoles
SDKSDK
SDK

8. SDK
iPhone
Android
Web
Gaming
consoles
SDKSDK
SDK
⚠

9. Engineers must be able to
communicate efficiently and
effectively

10. With the tips in this talk you should be able to

11. With the tips in this talk you should be able to
• Improve your own processes

12. With the tips in this talk you should be able to
• Improve your own processes
• Enhance your code quality

13. Feature specs

14. A good spec:

15. A good spec:
• Captures what a feature is and how it should work (the "what" and "how")

16. A good spec:
• Captures what a feature is and how it should work (the "what" and "how")
• Describes a public interface

17. A good spec:
• Captures what a feature is and how it should work (the "what" and "how")
• Describes a public interface
• Provides context (the "why")

18. A good spec:
• Captures what a feature is and how it should work (the "what" and "how")
• Describes a public interface
• Provides context (the "why")
• Defines UML for the public API

19. An example...

20. # User login flow
Users should be able to login through the `UserApi` defined
in the framework. An instance of the `UserApi` is obtained
through `MyFramework.userApi`. Framework users can call
`UserApi.login(username, password)` to trigger a login. The
`login` method returns a `Promise` that's fulfilled when the
`login` call completes sucessfully or with a failure. In
case of `success` the caller receives an `AccessToken`. In
case of `failure` the caller receives a `LoginError`.
In case the user provides invalid credentials, the server
returns a `LoginError.invalidCredentials` error. This is
also true if `login` is called with empty credentials.
...

21. # User login flow
Users should be able to login through the `UserApi` defined
in the framework. An instance of the `UserApi` is obtained
through `MyFramework.userApi`. Framework users can call
`UserApi.login(username, password)` to trigger a login. The
`login` method returns a `Promise` that's fulfilled when the
`login` call completes sucessfully or with a failure. In
case of `success` the caller receives an `AccessToken`. In
case of `failure` the caller receives a `LoginError`.
In case the user provides invalid credentials, the server
returns a `LoginError.invalidCredentials` error. This is
also true if `login` is called with empty credentials.
...
The Happy Path

22. # User login flow
Users should be able to login through the `UserApi` defined
in the framework. An instance of the `UserApi` is obtained
through `MyFramework.userApi`. Framework users can call
`UserApi.login(username, password)` to trigger a login. The
`login` method returns a `Promise` that's fulfilled when the
`login` call completes sucessfully or with a failure. In
case of `success` the caller receives an `AccessToken`. In
case of `failure` the caller receives a `LoginError`.
In case the user provides invalid credentials, the server
returns a `LoginError.invalidCredentials` error. This is
also true if `login` is called with empty credentials.
...
The Happy Path
Failures and
exceptions

23. Keep descriptions brief

24. ```uml
interface UserApi {
'@error LoginError.invalidCredentials'
'@error_description thrown if the user provides invalid
credentials'
+login(username: String, password: String) ->
Promise<AccessToken>
}
interface AccessToken {
+token: String
+expiresAt: Date
+refreshToken: String
+refreshExpiresAt: Date
}
```

25. Make sure to add sources when
needed

26. Sometimes it's not obvious
what's missing in a spec

27. Sometimes it's not obvious
what's missing in a spec
Especially when edge cases are missing

28. I ♥ writing tests

29. Introducing:

30. Introducing: Gherkin

31. Gherkin
The Building Blocks

32. Gherkin
The Building Blocks
• Given

33. Gherkin
The Building Blocks
• Given
• When

34. Gherkin
The Building Blocks
• Given
• When
• Then

35. Given: describes the
environment (preconditions)

36. When: describes the action you
want to test

37. Then: describes the environment
after the action is performed

38. Gherkin tests help you to:

39. Gherkin tests help you to:
• Understand a feature

40. Gherkin tests help you to:
• Understand a feature
• Know when a feature is fully implemented

41. Gherkin tests help you to:
• Understand a feature
• Know when a feature is fully implemented
• Discover edge cases

42. An example...

44. Given a valid username and password

45. Given a valid username and password
When using these credentials to call the login service

46. Given a valid username and password
When using these credentials to call the login service
Then a valid token should be stored

47. Given a valid username and password
When using these credentials to call the login service
Then a valid token should be stored
Then the valid token should be surfaced to the caller of the login method.

49. Given a valid username and an invalid password

50. Given a valid username and an invalid password
When using these credentials to call the login service

51. Given a valid username and an invalid password
When using these credentials to call the login service
Then the credentials error returned by the service should be surfaced to the
caller of the login method

53. Given a valid username and an empty password

54. Given a valid username and an empty password
When using these credentials to call the login service

55. Given a valid username and an empty password
When using these credentials to call the login service
Then the credentials error returned by the service should be surfaced to the
caller of the login method

57. Given a empty username and an empty password

58. Given a empty username and an empty password
When using these credentials to call the login service
Then the credentials error returned by the service should be surfaced to the
caller of the login method

60. Given a empty username and an non-empty password

61. Given a empty username and an non-empty password
When using these credentials to call the login service
Then the credentials error returned by the service should be surfaced to the
caller of the login method

62. A completed spec is submitted
for review

63. Focus during the review phase

64. Focus during the review phase
• Ensure that the spec is clear

65. Focus during the review phase
• Ensure that the spec is clear
• Test links to the documentation and compare them to the written spec

66. Focus during the review phase
• Ensure that the spec is clear
• Test links to the documentation and compare them to the written spec
• Review the UML for correctness

67. Focus during the review phase
• Ensure that the spec is clear
• Test links to the documentation and compare them to the written spec
• Review the UML for correctness
• Check that the feature is possible within your platform

68. Focus during the review phase
• Ensure that the spec is clear
• Test links to the documentation and compare them to the written spec
• Review the UML for correctness
• Check that the feature is possible within your platform
• Validate the tests and make sure they're complete

69. Focus during the review phase
• Ensure that the spec is clear
• Test links to the documentation and compare them to the written spec
• Review the UML for correctness
• Check that the feature is possible within your platform
• Validate the tests and make sure they're complete
• Make sure that at least one member from every platform reviews and
approves

70. During the implementation phase

71. During the implementation phase
• Every team will work on the features at roughly a different time

72. During the implementation phase
• Every team will work on the features at roughly a different time
• Versioning does not have to be identical within teams

73. During the implementation phase
• Every team will work on the features at roughly a different time
• Versioning does not have to be identical within teams
• Make sure that every team can work at their own pace

74. During the implementation phase
• Every team will work on the features at roughly a different time
• Versioning does not have to be identical within teams
• Make sure that every team can work at their own pace
• Just make sure that big deadlines are delivered in time

75. Summary

76. Summary
• Make sure you write feature specs that cover public APIs.

77. Summary
• Make sure you write feature specs that cover public APIs.
• A feature spec should cover the what, how and why without dictating
implementation details that aren't relevant to all platforms.

78. Summary
• Make sure you write feature specs that cover public APIs.
• A feature spec should cover the what, how and why without dictating
implementation details that aren't relevant to all platforms.
• Add Gherkin tests as a means of testing. This allows you to capture a minimum set
of tests that can be used while implementing a feature and aids a TDD approach
towards development.

79. Summary
• Make sure you write feature specs that cover public APIs.
• A feature spec should cover the what, how and why without dictating
implementation details that aren't relevant to all platforms.
• Add Gherkin tests as a means of testing. This allows you to capture a minimum set
of tests that can be used while implementing a feature and aids a TDD approach
towards development.
• Make sure to cross your t-s and dot your i-s during the review phase. You want at
least one review from a team member of each platform.

80. Summary
• Make sure you write feature specs that cover public APIs.
• A feature spec should cover the what, how and why without dictating
implementation details that aren't relevant to all platforms.
• Add Gherkin tests as a means of testing. This allows you to capture a minimum set
of tests that can be used while implementing a feature and aids a TDD approach
towards development.
• Make sure to cross your t-s and dot your i-s during the review phase. You want at
least one review from a team member of each platform.
• Allow platforms to diverge and work at their own pace. It's okay if feature sets
temporarily differ as long as deadlines are met.

82. Thank you