/Best Practices

How To Document Design System Components

- Paul Scanlon tl;dr: A look at how the most popular component libraries and design systems build and maintain their docs.

featured in #517

Writing Commit Messages

- Simon Tatham tl;dr: “When I’ve looked at other guides, they don’t seem to be focusing on the most important things. The one that first started me making notes towards this article consisted of a 7-point list of guidelines, most of which were tiny details of the initial ‘subject line’ part of the commit – what tense to use, whether to end it with a full stop, capitalisation – and the final rule just said ‘Use the body to explain what and why vs. how’.” Simon shares his approach. 

featured in #516

Use Abstraction To Improve Function Readability

- Palak Bansal Mark Manley tl;dr: The team at Google compares two functions and highlights how one is easier to follow due to its consistent level of abstraction, providing a top-down narrative of the code’s logic. createPizza is a high-level function that delegates the preparing, baking, and boxing steps to lower-level specialized functions with intuitive names. Those functions, in turn, delegate to their own lower-level specialized functions (e.g., heatOven) until they reach a function that handles implementation details without needing to call other functions.

featured in #515

Test Failures Should Be Actionable

- Titus Winters tl;dr: “When a test fails, you should be able to begin investigation with nothing more than the test’s name and its failure messages — no need to add more information and rerun the test.” Titus shares examples.

featured in #513

How To Document Design System Components

- Paul Scanlon tl;dr: A look at how the most popular component libraries and design systems build and maintain their docs.

featured in #513

JWTs vs. Sessions: Which Is Right For You?

- Lydia Gorham tl;dr: Both JWTs and session cookies are viable approaches to solving the issue of persisting authentication and authorization context in a stateless HTTP world, but they take fairly different approaches that have their own pros and cons.” Lydia breaks down the trade-offs and explains how you can use JWTs and sessions together to achieve a best of both worlds.

featured in #512

Managing Authorization Data In Microservices

- Graham Neray tl;dr: Authorization in a microservices environment becomes more complex. You need to think about: (1) Storing the data—should your authorization data live with application data, or in a separate service? (2) Accessing the data—if the data is separated, how do you bring it together to make the authorization decision? (3) Modeling the data—if authorization data and application data can be the same, how do you find the right format (i.e., data model) that fits all use-cases? Read on to learn more. 

featured in #500

Designing APIs For Humans: Error Messages

- Paul Asjes tl;dr: A valuable error message should: (1) Use the correct HTTP status code. (2) Wrap the error in an “error” object. (3) Be helpful by providing the error code. (4) The error type. (5) A link to the relevant docs. (6) The API version used in this request. (7) A suggestion on how to fix the issue. Paul shares an example by Stripe.  

featured in #499

The Developer’s Guide To SSO

tl;dr: Implementing single sign-on (SSO) is often the first step to selling to enterprises and can function as the difference maker in your company's success. This guide explains what SSO is, why it's critical for enterprises, and best practices for getting it up, running, and integrated with your app. 

featured in #495

The Ideal PR Is 50 Lines Long

- Greg Foster tl;dr: “50 lines is a sweet spot across speed, review comments, revert rate, and total coding volume. If you’re willing to accept a range, I can recommend 25-100 lines per PR. According to the data, we see that time-to-review, time-to-merge, and review comments per line all get better the smaller you make your PRs. There is a limit though: under 25 lines, and you start suffering a higher revert rate, as well as a lower total code shipped.”

featured in #490