How (not?) to write a JS framework

3. How (not?) to write a JS framework Best practices, gotchas, todos and lessons learned(the hard way)

4. Title OHAI!

5. Who’s this guy again? • The name’s Carcea. Alex Carcea. • Been tinkering with code since forever (Pascal, C / C++, Java, C#, Lisp, Haskell, Python, Ruby etc) • Been doing front-end since high-school (ActionScript, Flash / Flex, JavaScript) • Been building a framework since 2015 (Vanilla.JS)

6. So, what’s this about? • How to approach writing a JS framework (or, frankly, any massive JS project) • Considerations / Lessons learned • Documentation • Guiding Principles • Documentation • Standards and Best Practices • Documentation • Testing (unit, manual, automated) etc. • (oh, and did I mention documentation?)

7. Phase 0: Conception Phase 1: Preparation Phase 2: Implementation Phase 3: Going public

8. Phase 0: Conception • (aka “Do I really need to write a JS framework?”) • Questions to ask yourself: • What problem am I trying to solve? • Do I fully understand its ramifications / implications (i.e., the problem domain)? • Are there any solutions to my problem already out there? • Can I glue some stuff together to provide a solution?

9. Phase 0: Confirmation • (aka “You might not need to write a JS framework...”) • All other options deemed inaccurate / insufficient / plain wrong? • Take a step back, give it some time, sleep on it • Discuss with peers, product, management and other stakeholders • Seek explicit written consent, writing a JS framework is not easy peasy!

10. Phase 00: Confirmation • (aka “You might not need to write a JS framework...”) • OK, but does my solution even work? • Experiment, whip up something quick and dirty • Create a proof-of-concept as a selling point, something palpable is easier to grasp

11. Phase 0: Conception Phase 1: Preparation Phase 2: Implementation Phase 3: Going public

12. Phase 1: Preparation • A good / successful framework should • Have great documentation • Be concise, consistent and easy to understand • Do the heavy lifting (through convention / configuration) • Stay out of the way

13. Phase 1: Guiding Principles • (aka “What’s my mantra?”) • Baseline set of (5-10) rules to preach... and practice! • Should ideally highlight: • Your ultimate end goal • Your perfect world development cycle • Should serve as a starting point for defining standards and processes

14. Phase 1: Standards and Best Practices • Standards • Enforce consistency and predictability • Ensure minimal ramp-up time / learning curve • Best Practices • Encourage reuse of common patterns • Eliminate frequently encountered code / logic issues

15. Phase 1: Technical Specification • Refine proposed solution(s) • Think before you code! • Smooth out any rough edges • Narrow down cross-dependencies • Eliminate unneeded artifacts • Keep it high-level • Answer these questions: What? Why? When? Where? How? • Where applicable, include class diagrams • Excellent ramp-up resource

16. Phase 0: Conception Phase 1: Preparation Phase 2: Implementation Phase 3: Going public

17. Phase 2: Implementation • (aka “The easy part”) • Urban myths and legends (read: “flat-out lies”) • “Code should be self-documenting” • “I only need critical path testing for this part” • “I’ll refactor this later” • “This should work in all supported browsers”

18. Phase 2: Tooling • (aka “The breezy part”) • Documentation (inline comments, public APIs, technical specification(s)) • Unit testing (sufficient useful code coverage) • Linters. Precompilers. Transpilers.

19. Phase 2: Tips & Tricks • (aka “Now we’re talkin’!”) • The usual stuff • Have a plan. Validate the plan. Stick to the plan. • Have a plan B. • Take a step (or fifteen) back. • Don’t build things you’ll only ever use once. • Abstract. Create wrappers for 3rd party libs. Build standardized APIs for common core logic. • A little “glue” goes a long way! • Facilitate. Build a style guide. Standardize.

20. Phase 2: Tricks & Treats • (aka “Proven unorthodox techniques”) • The unusual stuff • Challenge yourself! • (... or, better yet, have someone else do it for you) • If it’s so easy, why don’t you do it? • Lessons Learned • Be uncomfortable. Embrace it. Thrive. • Speak out. Challenge the status quo. Change the status quo. • Accept defeat. Learn from it. Move on.

21. Phase 2: Code Reviews • (aka “Am I building the thing right?”) • The perfect scenario • Check that code adheres to standards and best practices • Validate code from a logical standpoint • Ensure business requirements are met • Pull down source branch, (compile,) run app to confirm functionality • Verify unit test results and actual code coverage • Never gonna happen...

22. Phase 2: Demos • (aka “Am I building the right thing?”) • The perfect scenario • Rehearse before you demonstrate • Set proper expectations in a timely fashion • Know your audience! • Take it slow: Call it. Do it. Check. Repeat. • Take notes (or have someone else do it) • Might happen every once in a while...

23. Phase 0: Conception Phase 1: Preparation Phase 2: Implementation Phase 3: Going public

24. Phase 3: Going public • (aka “Wait… Another JS framework?!?”) • Things to consider • If it’s not documented, it doesn’t exist! • Dependency hell: introduce clear, consistent versioning… and stick to it! • tl; dr: Code examples. Live code examples. Plenty of live code examples.

25. Phase 3: … and not going crazy • (aka “Not another JS framework!”) • Other things to consider • Don’t take it personal! • (Well, maybe just a little bit…) • You gave it your best! • (... or did you?) • You’ve asked for it!

26. Title Questions? Answers?

27. Title KTHXBAI!