<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Daniele Perito on Medium]]></title>
        <description><![CDATA[Stories by Daniele Perito on Medium]]></description>
        <link>https://medium.com/@daniele_8632?source=rss-9e8300851cc1------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*VDUwXO4AeFKoB5tn.</url>
            <title>Stories by Daniele Perito on Medium</title>
            <link>https://medium.com/@daniele_8632?source=rss-9e8300851cc1------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 14:46:01 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@daniele_8632/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[How data and machine learning shape Faire’s marketplace]]></title>
            <link>https://craft.faire.com/how-data-and-machine-learning-shape-faires-marketplace-510855c4a9bc?source=rss-9e8300851cc1------2</link>
            <guid isPermaLink="false">https://medium.com/p/510855c4a9bc</guid>
            <category><![CDATA[data]]></category>
            <category><![CDATA[marketplaces]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[analytics]]></category>
            <dc:creator><![CDATA[Daniele Perito]]></dc:creator>
            <pubDate>Wed, 27 Oct 2021 19:28:17 GMT</pubDate>
            <atom:updated>2024-05-14T18:15:52.710Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*F0DPzexePvjFRVOUPN5RVg.jpeg" /></figure><p>By: <a href="https://www.linkedin.com/in/danieleperito/">Daniele Perito</a>, <a href="https://www.linkedin.com/in/chen-peng-4a728b19/">Chen Peng</a></p><p><a href="https://www.faire.com/?utm_source=google&amp;utm_medium=cpc&amp;utm_campaign=SEM_AW_AMER_CA___RTL_BR___EXT&amp;keyword=faire%20wholesale&amp;matchtype=e&amp;device=c&amp;adgroupid=74190523370&amp;gclid=Cj0KCQjw5oiMBhDtARIsAJi0qk1cdbp6L27KE5fnYKSkQt2YCnA9-ZJaB177PkyKbQGCPXGMdyMp30YaApmUEALw_wcB">Faire</a> is an online marketplace that connects the world’s best independent brands with local retailers. There are over 30,000 brands and over 250,000 retailers using the platform across Europe and North America. At Faire, our mission is to empower these entrepreneurs to chase their dreams using the power of tech, data, and machine learning.</p><p>We designed our marketplace to serve our community and create a system where if our customers are successful, we are as well. Retailers on Faire can buy inventory upfront paying 60 days later (Net60 payment terms) and leverage free returns. That way retailers can buy confidently, knowing that if some products don’t sell in their stores, they can return them before disrupting their cash flow. Brands on Faire benefit from analytics and marketing tools that allow them to grow their customer base and ultimately their business. As a marketplace that serves small businesses, our primary goal is to increase sales for both our brands and our retailers.</p><p>Offering these value propositions and acting as a matchmaker between brands and retailers requires dozens of models that span the gamut of machine learning and data techniques, from information retrieval to entity resolution to anti-fraud/risk with binary classifiers to operations research and econometrics. Additionally, we must maintain a world-class data and experimentation infrastructure that allows us to collect/store data and make good decisions based on the actions and preferences of our customers.</p><p>In this post, we describe a few examples of the data-related challenges we work on as well as the general organization of the team behind it all.</p><h3>Our Customers</h3><p>As a marketplace, we have two interlocking customer journeys to describe: our brands join the platform to sell products and our retailers come on the platform to find great products to buy.</p><h3>Brands</h3><p>Brands are the makers of amazing and unique products. On Faire, they are typically small to medium businesses that make products to fulfill their passion. The products range from hand-poured scented candles, to apparel, furniture, toys, food, novelty items, and many other categories.</p><p>Brands typically first hear about Faire through our referral program, paid marketing, or organically through word of mouth. The data team helps optimize these channels and make sure that we onboard the best brands in the world and help them find success on our platform.</p><p><strong>Brand Acquisition</strong></p><p>Demand-supply balance is critical for the health of our marketplace. If we onboarded too many brands in a given period we would run the risk of having many of them receive little to no sales, hurting brand experience and retention. Our team is therefore constantly on the lookout and uses machine learning and econometrics techniques to establish the right number and mix of brands that should be acquired onto the platform in a given time period. With tens of thousands of brands wanting to join Faire, we must prioritize the brands that have the highest likelihood of being successful on the platform. For that reason, when a brand joins we look at hundreds of features about them: from the quality of their photography to the popularity of their website. We combine all the information and feed it into a machine learning model that predicts the success of the brand in the marketplace. The predictions are then fed to a team of human reviewers that act in concert with the machine learning model and double-check that our decisions are correct to maximize the likelihood that a great brand will be accepted.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*HvWboKA1Sd8UrsSR.gif" /><figcaption>Faire matches supply (wholesale brands) and demand (retailers) to create transactions and network effects makes the matching more effective when we have balanced supply and demand growth. We use models to assess the marginal impact of additional acquisition efforts, especially in cases of strong imbalance (e.g. if Supply &gt;&gt; Demand in a specific category, then adding an additional unit of supply will not be beneficial to the marketplace).</figcaption></figure><p><strong>Brand Success</strong></p><p>After a brand is approved to join the platform, it’s time to collect information about their product catalogue and profile, with the purpose of increasing their chance to succeed. How do we collect high-quality product information and how do we advise brands on what characteristics their brand profile should have to maximize the likelihood they get their first few sales on Faire?</p><p>We have two primary ways to do this. The first is by having models in production that help our brands and our internal teams fill out high-quality information for each product. For example, each product can be tagged with 1 of three thousand distinct product types (e.g., Plant Pot Stand or Baby Nail Scissors or Pet Indoor Tent). It is daunting for a person to find the right product type for a product among a list of thousands, but we give customers a sorted list of likely product type suggestions to help them out. We have a model that, given a product’s name, description and images, uses neural networks to suggest the closest product type tag in the embedding space of the product’s text and images.</p><p>Additionally, as brands fill out their profile we want to give them actionable insights on how to improve their catalogue and their chances of succeeding on Faire. For example, brands that upload all their products on Faire receive 40% more impressions and orders in their first 30 days on the platform, this is driven by the fact that retailers prefer brands with full catalogue information. To give brands accurate insights on what to work on, we’ve developed causal inference models that look through millions of historic interactions on the website and find the brand profile and product attributes that strongly correlate with and can be proven to casually increase sales. This is a difficult task because there are many confounding factors and we must isolate the important ones to be able to truly help our brands.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*TkUqi5rWSnM2uGRW.gif" /><figcaption>We use various causal inference techniques to identify the causal impact of brand behaviour change to brand sales growth. The above graph is an illustration of using Instrumental variable technique to assess how a brand’s First 30D success impacts their long-term performance on the marketplace. This causal inference technique recently won the <a href="https://www.nobelprize.org/prizes/economic-sciences/2021/press-release/">2021 Nobel Prize in Economics</a>.</figcaption></figure><p>As retailers become established on the platform, it’s important for Faire to highlight the highest-performing brands to provide retailers with the right information to make the best purchasing decisions. Our Top Shop program highlights our top brands that meet certain eligibility criteria. Finding the right eligibility criteria requires constant work from the data team to find the criteria that can be rigorously proven to lead to the best outcomes for brands and retailers on the platform.</p><p><strong>Faire Direct — a retailer referral program</strong></p><p>Brands on Faire have the ability to invite prospective and their existing retailers to join Faire through the Faire Direct program. When retailers join Faire through a brand’s invite, they get $100 and a year of free shipping with the referring brand. The program requires countless optimizations powered by the data team. For example, brands can refer retailers in different geographies that speak different languages. The referrals are typically done through an email invite sent via Faire. With only the email address of the retailer, the data team at Faire offers language predictions to the brand because referrals sent in the language of the retailer have a much higher chance of converting.</p><h3>Retailers</h3><p>The retailers on our platform are part of the millions of independent stores around the world. They are curators of great experiences and strive to find the best and most unique products to showcase in their stores, both offline and online. Great inventory is key to their success and we serve them by providing great product recommendations, value propositions like Net60, and free returns that help them buy with confidence. If we do our job well, their sales grow and they become more successful.</p><h3>Search and Recommendations</h3><p>Our retailers come to our platform with two distinct “shopping modes” — a focused mode with higher intent and conviction; and an inspirational one with lower intent and an eagerness to find great products without a crisp idea of exactly what those products will be. Those two modes are served by our search and recommendations teams, respectively.</p><p>In search, our job is to respond to a text query and find the best possible products that match the intent behind the query in real-time. Each query goes through various stages and models to help understand its category and type. The query is then sent to our ElasticSearch cluster where we retrieve matched products according to a scoring function that’s tuned to balance precision and recall. Then, we retrieve a candidate set of a thousand products that we then score using a first pass ranker. For each product, we retrieve hundreds of features from our Redis feature store and then pass the products through an XGBoost model that predicts the probability that the product will be added to cart. Doing all of this within a couple of hundreds of milliseconds is not trivial and we plan to publish additional articles on how we built and migrated to our new search ranking infrastructure.</p><p>The same ranking and scoring infrastructure we built for search is reused for many other surfaces, including category-based navigation, product carousels on the product details page, the brand profile page where each brand lists its own products. In each of these cases, the retrieval step might be slightly different but then the candidate set coming from the retrieval goes through the same unified infrastructure backed by Redis and a collection of XGBoost models. For example, retrieval for the recommendations on the product detail page is done by searching similar products to the current product in the embedding space learned by our recommendation system.</p><p>Our recommendation embeddings are learned from a combination of preference data (clicks, add to carts, favorites, and orders) and features about brands, products, and retailers. For retailers, this includes the style quiz answers that they provide upon sign up. Learning embeddings with a hybrid recommender system helps with the cold start problem and allows us to have high-quality embeddings for new and established customers. The embeddings calculated this way are a foundational resource that’s used across various models at Faire. For example, in the search ranking model described above one of the features captures similarity in embedding space between a retailer searching and each product in the candidate set. This way we can personalize the products we show all around the website.</p><p>The efforts behind our search and ranking systems are supported by a machine learning infrastructure team that maintains our core ranking infrastructure. From the libraries, we use to train and test ranking models to the Redis cluster that’s used to serve features in real-time and the feature monitoring systems that alert us when our features are drifting. Maintaining a real-time ranking infrastructure that does all the steps described above in a couple of hundreds of milliseconds requires lots of clever engineering that we will describe in future posts.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LyqFe65X2SLVJPOCfjyvRA.gif" /><figcaption><em>Overall architecture of our ranking infra</em></figcaption></figure><p>These systems and models described all center around a core problem for our retailers — -finding relevant and personalized products that they’ll want to buy. However, our ranking systems also need to accommodate another set of customers: our brands. The Search &amp; Recommendations team works hard to balance retailer considerations like relevance, conversion, and personalization with brand considerations such as receiving enough orders to justify the efforts of joining the platform. This is extremely challenging because optimizing our system for these two sets of customers at the same time introduces potentially competing goals in the scoring function: on the one hand, we want to show our retailers products that are likely going to be loved and purchased; on the other hand, we want to give a fair shot to new brands that don’t have a lot of data associated with them in the system yet. For this, we have developed a multi-armed bandit system that intelligently boosts brands in their first weeks on the platform and maximizes the likelihood that new brands will receive sufficient orders without noticeably compromising the quality of results we give to our retailers.</p><p><strong>Managing default risk</strong></p><p>As we mentioned above, we designed our value propositions to help retailers buy with confidence and minimize their risk. For this to happen we had to develop a number of machine learning models and systems that allow Faire to efficiently facilitate transactions between brands and retailers and assume the ultimate repayment and return risk for these transactions. Our retailers don’t have to pay until 60 days after placing an order and if they don’t like our products they can return anything that didn’t sell. Some retailers never pay us back and we need to manage this risk in order to be able to continue offering our core value propositions.</p><p>When a retailer signs up we immediately tell them two pieces of information: whether or not they qualify for Net60; and if they do qualify, what’s the maximum amount they can order at any point in time under the Net60 program, (their “terms limits”). To determine this we use a combination of XGBoost models that predict the likelihood that a retailer would default (fail to repay us) on their first order. One of the primary challenges of these models is that when a retailer signs up we have very little information about them. The team has spent a lot of effort finding features that correlate with repayment and non-repayment.</p><p>After a retailer places their first few orders, it’s time for us to reassess their risk profile using all the new data that we were able to collect from their interactions with the system. Things like their failure to pay previous invoices or the failure rates of their card on file. Every day, we run a model that runs new risk predictions for each retailer on the platform and generates recommendations to either increase a retailer’s limits, decrease them or leave them as they are. Retailers queued for limit increases and decreases are then passed on to a human who reviews the retailer one last time to make sure we are making accurate decisions.</p><p><strong>Shipping Cost Prediction</strong></p><p>When a retailer is ready to checkout their cart, we must give them an estimate of how much their shipping costs are going to be. Providing an accurate shipping cost estimate helps us improve conversion and earn the trust of retailers. This task is complicated by a few different factors: 1) each brand ships products from their own warehouses and costs can vary wildly depending on shipping location 2) from a lot of our products we do not have accurate dimensions and weights, these attributes are necessary for accurate shipping estimates. To help with this problem, we trained a model that uses hundreds of features and for a certain set of products in a cart predicts their dimensions, weights and combines them with information like the distance between a brand’s warehouse and the purchasing retailer.</p><p><strong>Retailer Growth &amp; Lifecycle Management</strong></p><p>Identifying efficient ways to acquire new retailers and keeping them engaged on the platform is critical for the sustainable growth and success of Faire. The data team partners closely with both marketing and product teams to optimize for retailer growth as well as retention. Some concrete challenges we help tackle here include: understanding the efficiency of various retailer acquisition channels (e.g. organic, paid, referral, etc.) and designing a framework to inform resource allocation across the channels to maximize output; cold-start personalization for a retailer’s homepage to enhance sign-up conversion and order rate; designing incentives and promotion campaigns to help retailers get started with their purchasing journey on Faire; tuning email and notification cadence and content to improve retailer retention and ordering frequency over time, etc.</p><p><strong>Insider — Faire’s subscription program</strong></p><p>In order to reward frequent retailer shoppers on Faire and make their buying experience truly frictionless, we offer a subscription program to active retailers on the platform. Retailers pay an affordable monthly subscription fee in exchange for free shipping from the majority of the brands on the platform and other types of benefits such as earlier access to new products. The data team helps optimize the pricing decision of the subscription program as well as the brand coverage model that determines which brands are included in the free-shipping offering for each individual subscriber — -to strike the right balance between the adoption rate and the economic viability of the program. A combination of experimentation, ML, and optimization techniques are involved in such efforts.</p><h3>Data Infrastructure &amp; Platform</h3><p>To support all the models above and help with data-driven decision-making at Faire, we also have significant resources dedicated to maintaining our data infrastructure and platform. The mission of the Data Infra &amp; Platform team is to build both reliable infrastructure systems to store, transform, and serve data efficiently at scale, as well as innovative platform tools and solutions to facilitate insights and intelligence generation using data.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*0AvRgRZ03WNfniq7.jpeg" /></figure><p><strong>Core Data Infrastructure</strong></p><p>The Core Data Infra (CDI) pod is responsible for the deployment, maintenance, and optimization of the data warehouse and workflow management platform (e.g. Airflow) that collects, stores, and transforms data into an easily consumable format in an efficient and reliable manner. CDI also provides critical infrastructure support to other data-related areas such as analytics engineering, experimentation platform, knowledge graph, and various ML systems used by other customer-facing teams. In the past year we migrated our data warehouse from Redshift to Snowflake to boost its functionality and flexibility, deprecated Kubeflow in favor of Airflow for ETL development and maintenance, piloted data quality monitoring in partnership with <a href="https://www.anomalo.com/">Anomalo</a>, and started the exploration of ML ops solutions. Many of these efforts will carry over into the future with more clear and aggressive milestones identified.</p><p><strong>Analytics Engineering</strong></p><p>It’s not enough to simply load bits into a warehouse — these bits also need to be organized and mapped into concepts that the rest of the organization can use and rely on. As a relatively new function in our data org, the Analytics Engineering pod is responsible for such translation and mapping tasks and operates as a critical bridge between infrastructure and business. More concretely, the AE pod works on the following:</p><ul><li>Core data model and pipeline development. This includes modeled tables around core entities like retailers, brands, orders, carts, emails, etc. as well as the ETL pipelines (Airflow DAGs) that produce these tables.</li><li>Metrics standardization and management. AE team is responsible for the definition of top-level metrics for the business and owns the single-source-of-truth of how such metrics should be derived from the underlying data.</li><li>Data Discovery. Data discovery is becoming increasingly more important as the business of Faire scales. Investing in the right approach to building a data discovery system will allow us to build a better data platform that helps various teams at Faire democratize and easily explore data, allowing us to keep tabs on important data assets and harness their full potential.</li></ul><p><strong>Experimentation Platform</strong></p><p>Experimentation Platform (EXP) is one of the most critical analytics infrastructure tools at Faire. Almost all product features and algorithm changes at Faire go through online A/B tests leveraging the EXP and at any given moment we have 20~40 experiments running on the platform simultaneously. The efforts in this area include both data and analytics engineering work in terms of building scalable and reliable user bucketing mechanisms and metric computation pipelines, as well as fairly sophisticated statistical modeling work to help detect bias, remove outliers, and reduce variance with CUPED. Interested readers can refer to previous <a href="https://craft.faire.com/how-to-speed-up-your-a-b-test-outlier-capping-and-cuped-8c9df21c76b">blog posts</a> we have published for more details.</p><p><strong>Knowledge Graph</strong></p><p>Faire’s goal is to become the go-to place for all the brands and retailers in the world interested in wholesale selling and buying. We started the Knowledge Graph (KG) team with the mission to collect and organize all the data on the web about these businesses — our potential customers — as well as the products they carry. This effort requires taking vast amounts of textual data and applying NLP techniques such as named entity recognition and entity resolution. This enables the KG team to generate information on the universe of brands and retailers that can readily be used to inform analyses and power our machine learning models.</p><h3>Roles on the Team</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*fHIpT_Nolr6u6Vje.gif" /><figcaption>Data team roles and responsibilities</figcaption></figure><p>Some of the most common questions we get from people interested in Faire are: what roles are available in the data team? What do they do, exactly?</p><p>The systems and models above are not easy to build and require a variety of different skills and specializations. From infra engineering to SQL and machine learning. Our data team is in charge of the systems end to end and therefore we need different roles in the team:</p><ul><li><strong>Data Engineers. </strong>Data engineers provide invaluable services to the rest of the team. They lay the foundation upon which all other teams build. They maintain the warehouse, make sure the data is correctly replicated across systems, make sure we can run scheduled jobs and get notified if they fail, and much more.</li><li><strong>Analytics Engineers. </strong>Analytics engineers organize all the data we collect and make sure it’s easily accessible by everyone else in the team. They build ETLs that organize all the data to maximize consistency and ease of understanding. That in turn helps all the other teams at Faire serve our customers.</li><li><strong>Data Scientists, Machine Learning. </strong>These data scientists specialize in building machine learning models that are used in ranking, recommendations, risk, and more. Their days are spent primarily building and fine-tuning models, but they also focus on maximizing learnings from previous experiments.</li><li><strong>Data Scientists, Inference. </strong>These data scientists specialize in helping rigorous decision-making at Faire. They leverage strong causal inference and experimentation expertise to help distill signals from noises and uncover invaluable insights about our customers and business from the underlying data.</li><li><strong>Machine Learning Engineers. </strong>Our machine learning systems need to make predictions in milliseconds. Machine learning engineers build, maintain, and operate these systems and also work closely with data scientists to train, test and deploy new machine learning models.</li></ul><h3>Conclusion</h3><p>Faire’s marketplace is full of challenging and stimulating data problems. Check out our <a href="https://www.faire.com/careers">careers page</a> to learn more about current opportunities at Faire, and stay tuned for future blog posts that will go deeper into each of the systems and models described in this article!</p><p><em>View all articles from the Faire Data Science team </em><a href="https://craft.faire.com/tagged/data-science"><em>here</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=510855c4a9bc" width="1" height="1" alt=""><hr><p><a href="https://craft.faire.com/how-data-and-machine-learning-shape-faires-marketplace-510855c4a9bc">How data and machine learning shape Faire’s marketplace</a> was originally published in <a href="https://craft.faire.com/">The Craft</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Faire’s Engineering Handbook]]></title>
            <link>https://craft.faire.com/handbook-89f166841ec9?source=rss-9e8300851cc1------2</link>
            <guid isPermaLink="false">https://medium.com/p/89f166841ec9</guid>
            <category><![CDATA[engineering]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[engineering-mangement]]></category>
            <dc:creator><![CDATA[Daniele Perito]]></dc:creator>
            <pubDate>Mon, 10 Feb 2020 19:52:13 GMT</pubDate>
            <atom:updated>2021-07-01T16:52:36.210Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aEgHOkrQSst2rG7kHW2w1w.jpeg" /></figure><h3>Faire’s engineering handbook</h3><p><em>The purpose of this document is to share, promote and discuss best practices among engineers.</em></p><p>This document summarizes and distills the knowledge of what processes, tools and techniques have or haven’t worked for us here at Faire. Some of the tenets and recommendations are subjective. In these cases, the purpose of the document is to promote convention and consistency, as these things help with collaboration.</p><h3>The 15 Minute Principle</h3><p>Before interrupting someone else with a question, spend 15 minutes researching the question (unless the world is on fire).</p><p>The same concept has been expressed in a lot of different ways. For example, “RTFM” is a popular acronym that expresses a related sentiment (a lot less kindly). The 15 minute principle provides constructive advice along the same lines.</p><p>There are several advantages stemming from this principle:</p><ol><li>In most cases, after 15 minutes of research, you should be able to answer the question yourself, without interrupting the flow of someone else’s work</li><li>Even if you don’t find the answer, you’ll learn a bit more about how the system works by searching for an answer yourself. That increases the shared knowledge of the system and it reduces the chances that next time you’ll find the need to ask a question</li><li>It incentivizes you to learn the tools and dig into other people’s code. Being able to follow code references with your favorite IDE goes a very long way in being self sufficient</li></ol><h3>Promote Cleanliness</h3><p>Naming inconsistencies, commented out code, unhelpful commit messages have lasting negative effects on your code base.</p><p>A general theme of this handbook is discussing ways to fight chaos. Code bases are large and complex entities that naturally devolve into a chaotic mess unless work is actively put to prevent that. That’s a universal principle that applies to everything.</p><p>Tests, code reviews, post-mortems are all tools we use to fight entropy and chaos in large codebases.</p><p>Promoting cleanliness is another way to fight chaos. Unclean, inconsistent code begets more unclean and inconsistent code that devolves into chaos.</p><h3>Investigate Issues</h3><p>It’s natural to try to explain away small issues that we can’t quite figure out immediately. Typically, people will say things like “it’s a small race condition” or “it only happens in the staging environment” without fully understanding how an issue happened. That’s wrong.</p><p><em>Small issues always compound into large issues</em>. You need to actively fight entropy and chaos. Whenever something doesn’t make sense, dig into it. More often than not you’ll find that the issue actually is part of a larger issue that needs to be fixed or at the very least explained.</p><h3>Code Reviews: Be Kind, Thorough and Aware of the Urgency</h3><ol><li>Be kind in code reviews. A practical advice here is to phrase comments as suggestions in the form of a question (e.g., How about changing thisName to thatName?)</li><li>Qualify how strongly you feel about something and whether you think that something is a “nit” vs a merge blocker</li><li>If you consistently disagree with someone on some pattern, have an offline discussion with them to clarify your respective opinions. PR comments aren’t the best place for really long discussions</li><li>Be thorough, the responsibility of shipped code lies both on the writer and the reviewer</li><li>Understand how urgent a code review and whether your teammate is blocked on it. If you know a teammate is blocked on your code review, review urgently. There are probably many people who are waiting on that code review (your fellow engineer, a PM waiting to look at the feature in staging, your customers, etc.).</li><li>A corollary of the rule above is, ask how urgent a review is if you are not sure</li><li>Accept criticism as a natural part of the process</li></ol><p>A corollary to this principle is, review your own code before asking for someone else’s review. The reviewer’s time should not be spent finding small typos or debug statements left lingering. In general, be mindful of other people’s time just as much as you are mindful of your own time.</p><h3>Tests</h3><p>Tests are one of the most discussed topics in engineering. There is a huge number of articles and books describing what to test, how to test, promoting writing tests, test frameworks, etc. It’s hard to add to that huge body of knowledge.</p><p>I suspect that part of the reason why we write so much about tests is that tests don’t seem to be strictly necessary to ship code. Our lazy selves make up all kinds of excuses to tell us that we don’t <em>really</em> need to write tests. That couldn’t be further from the truth, tests are absolutely essential to maintaining code clean.</p><p>A few short things to summarize:</p><ol><li>Tests are A Good Thing™</li><li>If you don’t see tests while reviewing a PR, ask for them</li><li>Test basically always pay themselves off, often immediately. There is a false dichotomy that you can either ship code fast or you can ship well tested code. More often than not tests pay themselves off in the natural course of writing a PR.</li></ol><h3>Optimize your code for readability</h3><p>This is another subject that has been discussed at length. A few key takeaways:</p><ol><li>Code is read a lot more than it is written. Therefore you should write code that is easy to read.</li><li>Use descriptive names. Naming is one of the hardest things to get right in programming. Avoid abbreviations as much as possible (a variable called current is a lot better than a variable called curr, the latter imposes a tiny cognitive load every time it is read)</li><li>Follow the style guide for consistency. When reviewing code make sure it meets the style guide suggestions.</li><li>Avoid long methods (typically longer than 20–50 lines of code). Long method names usually indicate that the method is doing more than it should. Break it up into smaller and simpler methods with a single utility.</li><li>Add comments to your code. With one major caveat, comments cannot help make sense of spaghetti code. A typical example are very long methods with comments every couple of lines. A better approach in those cases is to refactor the code into smaller, self-describing method calls</li></ol><h3>Use Post-mortems to identify the root cause of past issues</h3><p>If you haven’t read it yet, we highly recommend you read the <a href="https://www.amazon.com/Checklist-Manifesto-How-Things-Right/dp/0312430000"><em>Checklist Manifesto</em></a>. The general idea of the book is how it’s possible to minimize faults in a system by learning from past mistakes and putting together [in software engineering, automated] processes to deal with those common mistakes. The most widely cited example of this is aviation safety.</p><p>Since the 70s, the number of deaths from crashes has been in steady decline even though the number of commercial passengers has increased dramatically. This huge success is the direct result of relentless investigation of past issues and adopting the learning from them.</p><p>Whenever there is a major bug or outage, hold a post-mortem meeting detailing the following:</p><ol><li>Time issue started</li><li>Time issue identified</li><li>Time issue resolved</li><li>Number of customers impacted</li><li>Root of the problem</li><li>Action items to prevent the issue from happening in the future</li></ol><p>#6 is perhaps the most important part of a post-mortem. Typically, you’ll want to add better metrics, tighter controls for certain common mistakes, more automation.</p><p>One thing to be careful of is avoiding adding toil when learning from post-mortems. As much as possible, you should try to prevent future mistakes with automation. Sometimes manual process is necessary, but always think about ways to automate the learnings.</p><h3>Metrics and Alerting</h3><p>In general, you are what you measure. This is a widely shared tenet that applies to more than engineering.</p><p>Make sure you have at the very least performance metrics and alerting set up. The existence of performance metrics will, in a very real sense, make your application faster. Alerting, when correctly applied, will make your application less bug ridden.</p><p>Other metrics you might want to keep an eye on are: test speed, test coverage and compilation speed.</p><h3>Learn the tools</h3><p>The tools you use are as important for your productivity as the language you choose or the technology you adopt. They can be a huge help, or an hindrance to your day to day happiness and productivity.</p><p>In general, you want to use an IDE that deeply understands the language you are using. The IDE will be able to discover a lot of issues for you.</p><p>Another important thing to learn is using a debugger. A lot of inexperienced engineers develop with “debug prints”. Debug prints are a classic example of toil (covered below) and should be avoided in a lot of circumstances.</p><p>A rule of thumb is that if you often find yourself having to deal with issues that stem from typos, you aren’t using the right tools or you aren’t using your tools as they are meant to be used. Find some time to shadow or pair with someone who is more familiar with the tools you use and see how they use them.</p><h3>If It Ain’t Broke, Don’t Refactor It</h3><p>Every line of code in every codebase could be likely rewritten in a flashier or more elegant way. While we all love writing code, we should be always be mindful of the fact that we aren’t writing code for its own beauty, we are writing code to help our customers. Large refactors are usually to be avoided, while smaller refactors and cleanups during the course of regular programming tasks are preferred and encouraged.</p><h3>Minimize Toil</h3><p><a href="https://landing.google.com/sre/book/chapters/eliminating-toil.html"><em>Toil is very well described in this section of the Google SRE’s Handbook.</em></a> We suggest you spend some time reading that handbook.</p><p>From that book: “Toil is the kind of work [tied to running a production service] that tends to be manual, repetitive, automatable, tactical, devoid of enduring value, and that scales linearly as a service grows.”</p><p>A software engineer’s time should be spent engineering solutions to problems. You should minimize toil and reduce it to at most 10–20% of your time (unless you are a production engineer). A lot of toil can be eliminated by better tools.</p><h3>Appendix — Recommended Reading</h3><ol><li><a href="https://landing.google.com/sre/book/index.html"><em>Google SRE Handbook</em></a> (Free)</li><li><a href="https://www.amazon.com/Checklist-Manifesto-How-Things-Right/dp/0312430000"><em>The Checklist Manifesto</em></a></li><li><a href="https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882"><em>Clean Code</em></a></li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=89f166841ec9" width="1" height="1" alt=""><hr><p><a href="https://craft.faire.com/handbook-89f166841ec9">Faire’s Engineering Handbook</a> was originally published in <a href="https://craft.faire.com/">The Craft</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>