<?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 Andrew Goldis on Medium]]></title>
        <description><![CDATA[Stories by Andrew Goldis on Medium]]></description>
        <link>https://medium.com/@agoldis?source=rss-1bb5b7a41f59------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*4QKGSCunaT4qNOGI.jpg</url>
            <title>Stories by Andrew Goldis on Medium</title>
            <link>https://medium.com/@agoldis?source=rss-1bb5b7a41f59------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Mon, 16 Nov 2026 17:51:29 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@agoldis/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[ Cypress test replays with Cypress Debugger]]></title>
            <link>https://agoldis.medium.com/cypress-test-replays-with-cypress-debugger-7850012835f3?source=rss-1bb5b7a41f59------2</link>
            <guid isPermaLink="false">https://medium.com/p/7850012835f3</guid>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[testing]]></category>
            <category><![CDATA[cypress]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[replay]]></category>
            <dc:creator><![CDATA[Andrew Goldis]]></dc:creator>
            <pubDate>Sun, 20 Aug 2023 00:39:17 GMT</pubDate>
            <atom:updated>2023-08-20T00:40:52.153Z</atom:updated>
            <content:encoded><![CDATA[<h3>Capture and replay everything that is happening in Cypress during CI runs with a free, open-source plugin cypress-debugger. It is like Playwright Traces but for Cypress.</h3><p>Cypress Test Replay is an exciting new feature that’s planned to launch in Cypress 13. Cypress ambassadors and the marketing team have been promoting Test Replay, emphasizing how good it is for debugging failed CI executions.</p><p>True, it is super-effective but is only available for Cypress Cloud paying subscribers.</p><p>Back in Feb 2023 we started working on <a href="https://cypress-debugger.dev/">cypress-debugger</a> — a free, open-source, standalone plugin that is equivalent to… Cypress Test Replay. We launched the plugin in May 2023. See the original video <a href="https://www.loom.com/share/6c2135fa1dce492ca997edd5cf56efe6?sid=2ad4a931-6049-4e1a-93e5-d91900b95d59">here</a>. Republishing the original blog post below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XQoffawRZiGbPsdDLWNYMg.png" /><figcaption>Cypress Debugger — capture and replay everything that is happening in Cypress during CI runs</figcaption></figure><p>When running Cypress in a CI pipeline, we get screenshots, videos, and terminal logs. Sometimes it’s not enough to debug a failed or flaky test. What if we could save everything that’s happening in a browser and capture the actual network requests, browser console messages for every cypress step, so that we can replay those steps after test completion?</p><p>Some of you can be familiar with <a href="https://playwright.dev/docs/trace-viewer">Playwright Traces</a>. So what if we had Cypress test replays or traces?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*SvherVQeWdRgpSLFvcjqUw.gif" /><figcaption>Replaying Cypress trace with Cypress Debugger (https://cypress-debugger.dev)</figcaption></figure><p>We have a plugin that does exactly that! <a href="https://github.com/currents-dev/cypress-debugger">https://github.com/currents-dev/cypress-debugger</a></p><p>The plugin is free and open source. You can start using it today on your CI setup. When installed it will capture:</p><ul><li>capture Cypress test execution steps</li><li>capture DOM snapshots for each step</li><li>capture browser console messages</li><li>capture browser the networks requests (HAR)</li></ul><p>All this information will be dumped into a simple JSON file that you can then load into a web player for replaying. The player is available at <a href="https://cypress-debugger.dev/">https://cypress-debugger.dev</a></p><p>After loading the file, you can replay the execution step-by-step, rewind, open browser developers tools to explore the actual DOM tree that was captured on every cypress step.</p><p>Here are a few examples of how to use this plugin in a CI environment (GitHub Actions):</p><ul><li><a href="https://github.com/currents-dev/cypress-debugger/blob/main/.github/workflows/example.yml">https://github.com/currents-dev/cypress-debugger/blob/main/.github/workflows/example.yml</a></li><li>Integrated together with cypress-cloud: <a href="https://github.com/currents-dev/gh-actions-example/tree/debugger-example">https://github.com/currents-dev/gh-actions-example/tree/debugger-example</a></li></ul><p>We were able to build this plugin by using amazing open-source packages like <a href="https://github.com/NeuraLegion/cypress-har-generator">cypress-har-generator</a> and <a href="https://github.com/rrweb-io/rrweb">rrweb</a>.</p><p>Please start using it today. Share your feedback. You can also play and change the code yourself.</p><p>The plugin currently supports only Chromium family browsers only.</p><p>We do plan to enable native support of this plugin as part of <a href="https://currents.dev/">Currents</a> and <a href="https://sorry-cypress.dev/">Sorry Cypress</a> dashboard.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7850012835f3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Cypress Dashboard vs Currents — Ultimate Comparison Guide]]></title>
            <link>https://agoldis.medium.com/cypress-dashboard-vs-currents-ultimate-comparison-guide-6c10ae553fdd?source=rss-1bb5b7a41f59------2</link>
            <guid isPermaLink="false">https://medium.com/p/6c10ae553fdd</guid>
            <category><![CDATA[saas-tools]]></category>
            <category><![CDATA[devtools]]></category>
            <category><![CDATA[qa]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[cypress]]></category>
            <dc:creator><![CDATA[Andrew Goldis]]></dc:creator>
            <pubDate>Fri, 04 Nov 2022 05:51:58 GMT</pubDate>
            <atom:updated>2022-11-06T06:23:54.485Z</atom:updated>
            <content:encoded><![CDATA[<h3>Cypress Dashboard vs Currents — Ultimate Comparison Guide</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*ZQvolL1FpoaYvwKz" /></figure><h3>A detailed comparison guide between Cypress Dashboard and the most popular alternatives — Currents and Sorry Cypress. Pricing, analytics, orchestration, load balancing, compatibility, parallelization, integrations and unit economics are compared between the solutions.</h3><p>Read the original publication at: <a href="https://currents.dev/posts/currents-vs-cypress">https://currents.dev/posts/currents-vs-cypress</a></p><p>Cypress is one of the most popular end-to-end front-end test automation frameworks, widely used by many companies worldwide. In addition to classic end-to-end browser-based tests, Cypress is being used for UI components testing, API tests, smoke testing and synthetics checks.</p><p>Eventually, when you start running a large number of tests in a CI pipeline, you start facing a few problems:</p><ul><li>sequential test execution takes a long time</li><li>test failures in CI environment are hard to reproduce and troubleshoot</li><li>flaky tests waste your team’s time and waste CI resources</li><li>performance and health of the test suite deteriorates</li></ul><p>Software and QA teams use a complimentary service like <a href="https://www.cypress.io/dashboard/">Cypress Dashboard</a>, <a href="https://currents.dev/">Currents</a> or <a href="https://sorry-cypress.dev/">Sorry Cypress</a> to resolve those issues, and additionally enjoy extra “perks”, like integrations with Slack, GitHub (and more), <a href="https://currents.dev/readme/api/introduction">REST API</a> (Currents only). Using those tools can greatly improve developer experience: save valuable time, resources and frustration, while keeping your tests suite under control.</p><p>For example, <a href="https://currents.dev/readme/guides/parallelization">parallelization</a> is a natural solution for sequential tests execution — it reduces overall build duration within a Continuous Integration environment.</p><p>Having video recordings, screenshots, call stack and exact source code location are very helpful for troubleshooting failed tests. Detecting and reporting flaky tests helps teams to improve the reliability and performance of their test suite. In addition, the dashboards collect and aggregate various stats and <a href="https://currents.dev/readme/insights/insights-and-analytics">metrics</a> related to the performance of your tests. Overall, dashboards provide a comprehensive testing experience and improve the efficiency of Cypress test suite.</p><p>There are currently two main alternatives to the Cypress Dashboard: Currents and Sorry Cypress. In this article, we’ll dive deep into comparing the features that those solutions offer.</p><h3>Overview</h3><h3>Cypress Dashboard</h3><p><a href="https://www.cypress.io/dashboard/">Cypress Dashboard</a> is the original service provided by Cypress.io — the company behind the open-source MIT-licensed Cypress runner. Used by many larger companies like PayPal, DHL, and Disney, it is the most popular, mainstream, but also the most expensive solution. The following are the main features it provides.</p><ul><li>Debugging and analytics</li><li>Test grouping and optimization</li><li>Parallelization and load balancing</li><li>Video recording, stack traces, and screenshots of failed tests</li><li>Flake detection</li><li>Integration with Slack, GitHub, GitLab, and Jira</li><li>Works with any CI provider</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*1hmKdkEp-3ytT-rc" /><figcaption><em>Cypress Dashboard Overview</em></figcaption></figure><h3>Sorry Cypress</h3><p><a href="https://sorry-cypress.dev/">Sorry Cypress</a> is the most known and popular alternative to Cypress Dashboard. With <a href="https://npmtrends.com/cy2">170K+ weekly downloads</a> and <a href="https://hub.docker.com/r/agoldis/sorry-cypress-director">5M+ downloads on Dockerhub</a>, it’s being used in many industries as a self-hosted, free, open-source, MIT-licensed solution that provides many of the essential features with theoretically unlimited tests recording and parallelization.</p><p>Sorry Cypress supports deployment on many cloud platforms, such as K8S, AWS, Azure, and Google Cloud. Apart from parallelization, and storing screenshots and videos, it provides integrations with GitLab, Github, BitBucket + HTTP Webhooks, progress tracking, and test grouping capabilities. However, as you will see from the features comparison below, it lacks features that may be important — like smart orchestration, permissions management, analytics and some integrations.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*JnhIxyBGl8pATybZ" /><figcaption><em>Sorry Cypress Overview</em></figcaption></figure><h3>Currents</h3><p><a href="https://currents.dev/">Currents</a> is a paid version of Sorry Cypress — it is a cloud-based, managed solution that is similar to the original Cypress Dashboard and has almost identical functionality while offering subscription plans that are 45–60% less expensive.</p><p>Here’s a high-level overview of Currents functionality, described in more detail in the next chapters:</p><ul><li>parallelization and smart orchestration by using historical data for reducing the tests execution time even more</li><li>debugging tools: screenshots and videos, stack traces and source code highlighting</li><li>history of test and spec files executions</li><li>integrations and automation: REST API, HTTP Webhooks, GitHub / GitLab / Slack and more</li><li>insights and reports like top failing tests, top flaky tests, runs status and failure rate, runs duration distribution, test suite size, spec files failure rate, flakiness analysis and stability</li><li>premium support, SSO, access controls, roles, flexible plans</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Q6YozVf4AxuXvK-o" /><figcaption><em>Currents Dashboard Overview</em></figcaption></figure><h3>Features Comparison</h3><h3>Parallelization and Orchestration</h3><h4>Basic Parallelization / Load Balancing</h4><p>All three tools provide basic parallelization to reduce test execution time by automatically splitting your tests across multiple CI machines. Parallelization allows using the full capacity of your CI fleet — each machine executes just a small subset of tests.</p><p>The dashboards provide instructions for each machine and automatically balance the tests without the need to manually configure the splits logic. The parallelization works on any CI provider that is capable of spinning a few workers / containers for the same build.</p><ul><li>Currents: ✅</li><li>Sorry Cypress: ✅</li><li>Cypress Dashboard: ✅</li></ul><h4>Optimal Parallelization and Smart Orchestration</h4><p>Both Currents and Cypress Dashboard implement optimal parallelization by using historical data to optimally sort the tests and produce a more predictable execution order.</p><p>By using the historical duration metric for each file, the files with the longest duration are getting prioritized. It helps reduce build duration even more. Sorry Cypress is the only solution that doesn’t support optimal parallelization.</p><ul><li>Currents: ✅</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ✅</li></ul><h4>Running Failed Specs First</h4><p>By running previously failed tests or tests with the highest fail rate first, you can be aware of the failing test as early as possible — it allows you to reduce CI resources usage, get faster feedback and deploy fixes sooner.</p><p>Cypress Dashboard is the only tool that provides the smart orchestration feature “Running failed specs first”, but it is only available to Business Plan customers.</p><ul><li>Currents: ❌</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ✅ 💼</li></ul><h4>Fail-Fast</h4><p>When a single test fails in your test suite, sometimes there is no point in executing the rest of the tests. Both Currents and Cypress Dashboard cab cancel the whole run when a test fails. It automatically cancels the build and marks it as failed. The primary advantage of using a <a href="https://currents.dev/readme/guides/fail-fast-strategy">fail-fast strategy</a> is reducing CI costs, it makes CI resources available to test quick fixes.</p><ul><li>Currents: ✅</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ✅</li></ul><h4>Test Grouping</h4><p>All three solutions provide a “test grouping” feature using which you can group tests by specific contexts like the browser, the operating system, the environment, etc., within the same run. Grouping tests have many benefits. For example, grouping by browser helps you to implement a CI strategy for Cross Browser Testing. Also, if you have a monorepo that contains many projects, you can group tests by projects in that monorepo.</p><ul><li>Currents: ✅</li><li>Sorry Cypress: ✅</li><li>Cypress Dashboard: ✅</li></ul><h4>Runs Cancellation</h4><p>Due to the distributed nature of running tests in parallel on multiple machines and limitations of Cypress architecture, cancelling a run via a CI provider can cause a <a href="https://currents.dev/readme/runs/run-timeouts">timeout</a>. That’s why it’s better to cancel/stop a run via a dashboard — they will send the cancellation request to CI machines associated with the run and will gracefully mark the run as cancelled, without causing a timeout.</p><p>Cypress Dashboard only allows cancelling the runs via dashboard UI, while Currents allows cancellation via dashboard UI and also via an API call, which (in combination with HTTP webhooks) allows customers to create powerful automation.</p><ul><li>Currents: REST API ✅, UI ✅</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: REST API ❌, UI ✅</li></ul><h3>Debugging and Troubleshooting</h3><h3>Record screenshots and record videos of failed tests</h3><p>All the tools allow you to capture auto-generated failed tests screenshots and videos to determine exactly where the failure happened. You can configure cypress runner to record <a href="https://docs.cypress.io/api/commands/screenshot">arbitrary screenshots</a> and <a href="https://docs.cypress.io/guides/references/configuration#Videos">videos of passed tests</a> as well.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*rKyO84OE4eUlfsGI" /><figcaption><em>Cypress Dashboard Test Troubleshooting View</em></figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*cG7Pw7Tkr9cUeefw" /><figcaption><em>Currents Test Troubleshooting View</em></figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*xeA2dOJOPnOlNhly" /><figcaption><em>Sorry Cypress Troubleshooting View</em></figcaption></figure><p>You can then replay the videos / screenshots for troubleshooting your test performance and execution during a CI run. The artifacts are stored on the respective services’ cloud storage and can be downloaded when needed.</p><ul><li>Currents: ✅</li><li>Sorry Cypress: ✅</li><li>Cypress Dashboard: ✅</li></ul><h3>CI Logs</h3><p>Currents and Cypress Dashboard also save and display the CI logs for the associated tests. Those logs capture the terminal output produced by cypress runner for later examining the execution trace of tests on a CI machine.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*NwM4oXyDhOGjAeEf" /><figcaption><em>Cypress Dashboard CI Logs</em></figcaption></figure><p>Together with cypress plugins like <a href="https://github.com/archfz/cypress-terminal-report">cypress-terminal-report</a> one can reproduce the commands used by cypress runner during its execution and pinpoint the exact reason for failure.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*w_huye6IHlX-Vblb" /><figcaption><em>Currents CI Logs</em></figcaption></figure><ul><li>Currents: ✅</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ✅</li></ul><h3>Errors Stack Trace</h3><p>For every test failure, the tools display the title of the failed test, the error stack trace, and the error message. Using the error stack trace, you can track down where the problem originates.</p><ul><li>Currents: ✅</li><li>Sorry Cypress: ✅</li><li>Cypress Dashboard: ✅</li></ul><h3>Test Runs History</h3><p>Both Cypress Dashboard and Currents provide a test runs history feature where you can see the previous executions of a test over its lifespan. Cypress Dashboard provides a basic explorer of tests runs history that only shows the execution results (pass / failure) and the associated git information.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*JDX10szEWYwdjuaL" /><figcaption><em>Cypress Dashboard — Test Runs History</em></figcaption></figure><p>Currents provides more information: duration, flakiness indication, outcome, and commit details. In addition, Currents allows browsing test history further into the past and includes information about executions from all the branches.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*qJg0aNaf8ClDmtKg" /><figcaption><em>Currents — Tests Runs History</em></figcaption></figure><ul><li>Currents: ✅</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ✅</li></ul><h3>Spec Files History</h3><p>Currents provides a unique ability to browsing executions history for each spec file. Similar to Test Runs History, you can explore past executions for each spec file: duration, flakiness indication, outcome, and commit details, includes data collected from from all the branches.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*zN_QYdvpZ4EZFO7g" /><figcaption><em>Currents — Spec Runs History</em></figcaption></figure><ul><li>Currents: ✅</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ❌</li></ul><h3>Test Source Code History</h3><p>Cypress Dashboard is the only service that allows browsing test source code history. This feature may be useful for discovering what changes to source code could trigger a failure or performance issues for a given test.</p><ul><li>Currents: ❌</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ✅</li></ul><h3>Flaky Tests</h3><h3>Flaky Tests Detection</h3><p>Flaky tests detection is supported by all three tools. A flaky test is an unreliable test that passes or fails across multiple retries of the test execution, despite no changes in the code. Suppose you executed a test, and it failed in the first run; then you execute it again without any code changes — and it unexpectedly passes.</p><p>Flaky tests are expensive to maintain — when they fail, they terminate the whole run, forcing reruns, waste of CI resources and reducing developers’ confidence in tests’ reliability.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*lLs0C-kT8hbB86Gf" /></figure><p><em>Cypress Dashboard — Flaky Tests Detection</em></p><p>To detect flaky tests, you must first enable <a href="https://docs.cypress.io/guides/guides/test-retries">automatic retries</a> within Cypress configuration. When a flaky test is detected within a run, all 3 tools add a visual “flaky” indicator to allow you to fix them at your earliest.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*5Lq-Q9udMa9bdWrp" /><figcaption><em>Currents — Flaky Tests Detection</em></figcaption></figure><ul><li>Currents: ✅</li><li>Sorry Cypress: ✅</li><li>Cypress Dashboard: ✅</li></ul><h3>Flakiness Insights</h3><p>For bigger test suites and complex testing environments, it can be useful to manage flakiness at macro level. Cypress Dashboard and Currents both provide flakiness management tools that aggregate flakiness metrics for a project, spec file and test levels.</p><p>The flaky tests analytics from Cypress Dashboard shows statistics like the number of flaky tests over time, overall flakiness, and the number of flakey tests or spec files grouped by severity. You can also explore an individual test flakiness rate and execution history.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*ZokuZ-tOORAyUdIK" /><figcaption><em>Cypress Dashboard — Flakiness Insights</em></figcaption></figure><p>Currents has several powerful tools for helping you with managing flakiness. It provides test-level or spec-file-level flakiness and failure rate explorer, together with their execution history. It allows you to identify tests or spec files with the highest flakiness rate, filtered by tag, branch or committer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*21A0i7VKKQsrmuDb" /><figcaption><em>Currents — Flakiness Insights: top flaky tests and spec files</em></figcaption></figure><p>In addition, it also provides project-level overview of flaky test and overall flakiness rate.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*fu01KvhVgzGoN9vd" /><figcaption><em>Currents — Flakiness Insights: project-level flakiness overview</em></figcaption></figure><ul><li>Currents: ✅</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ✅</li></ul><h3>Environment and Build Information</h3><p>The tools allow users to explore the details of builds execution and progress.</p><ul><li>Git Information — for each build, you can see information like author name, commit message, branch name, and PR details</li><li>Environment Information — browser and device information for each build</li><li>Run/Spec/Test Duration — duration of your builds, spec files, and the time spent on each test</li><li>Expected Duration — show the expected duration which is based on historical data</li><li>Machines Distribution — real-time distribution of tests across the CI machines</li></ul><p>The timeline view lets users view parallel test execution, and the bar chart view makes it easier to view longer-running tests. Cypress Dashboard and Current also integrate with historical data like expected duration to enhance the experience.</p><h3>Integrations</h3><h3>GitHub + GitHub Enterprise Integration</h3><p>The tools can seamlessly integrate with GitHub, providing timely updates about tests execution progress and results:</p><ul><li>Commit Status updates</li><li>PR comments</li></ul><p><a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks">Commit Status updates</a> indicate the health of a commit within a repository.</p><p>PR Comments provide detailed information about your test results within the PR comments section. For example — the number of passed, failed, skipped or flaky tests, the status of the final test run, OS and browser visions, the first ten failure runs, and many more. Only Cypress Dashboard and Currents implement posting PR comments.</p><p>GitHub Enterprise integration is only included in Cypress Dashboards’ Business and Enterprise paid pricing plans. In contrast, Currents include it in all the plans, and Sorry Cypress provides it free of charge.</p><ul><li>Currents: PR Comments ✅, Status Checks ✅</li><li>Sorry Cypress: PR Comments ❌, Status Checks ✅</li><li>Cypress Dashboard: PR Comments ✅, Status Checks ✅</li></ul><h3>GitLab + Self-Hosted GitLab Integration</h3><p>Only Cypress Dashboard and Currents have GitLab Integration. GitLab commits statuses ad Merge request comments (MR) are enabled by default. Commit status contains the test result to avoid merging failing tests. In addition to statuses, the integration indicates any flake tests to avoid merging flaky tests.</p><p>MR comments provide a test run summary with statistics like test counts, run info, and a failed or flaky test summary.</p><ul><li>Currents: MR Notes ✅, Status Checks ✅</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: MR Notes ✅, Status Checks ✅</li></ul><h3>Slack Integration</h3><p>Slack integration promotes cross-team collaboration and reduces the time to find failed tests — it is available in Currents, Cypress Dashboard and in Sorry Cypress. While the integrations vary by the amount configuration options, in general, they are quite similar in purpose — posting build results to your organization’s Slack channel.</p><ul><li>Currents: ✅</li><li>Sorry Cypress: ✅</li><li>Cypress Dashboard: ✅</li></ul><h3>Bitbucket Integration</h3><p>The tools can integrate with Bitbucket + Enterprise, posting commit status updates However, only Cypress Dashboard supports posting PR comments for BitBucket integrations.</p><ul><li>Currents: PR comments ✅, Status Checks ❌</li><li>Sorry Cypress: PR comments ✅, Status Checks ❌</li><li>Cypress Dashboard: MR Notes ✅, Status Checks ✅</li></ul><h3>Jira</h3><p>Cypress Dashboard is the only tool that natively integrates with Jira — it allows create Jira issues for a specific test case and allows one to explore Jira ticket history.</p><ul><li>Currents: ❌</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ✅</li></ul><h3>HTTP Webhooks</h3><p>HTTP Webhooks allow you to implement custom integrations that are not provided out-of-the-box. For example, you can automatically create a ticket in your bug tracking system based on the results of incoming webhook, or store test run results in a data lake for analysis and improvements. Only Currents provides HTTP Webhooks integration.</p><ul><li>Currents: ✅</li><li>Sorry Cypress: ✅</li><li>Cypress Dashboard: ❌</li></ul><h3>REST API</h3><p>In addition to HTTP Webhooks, you can access your test results and artifacts programmatically using Currents’ REST API. That unlocks even more possibilities for customizing and integrating Currents into your team’s workflow.</p><ul><li>Currents: ✅</li><li>Sorry Cypress: ❌</li><li>Cypress Dashboard: ❌</li></ul><h3>Analytics and reporting</h3><p>Having a macro-level aggregated insights can help you to use your CI resources more efficiently, identify problematic tests to focus team’s efforts, and detect changes in test suite health trends like duration, failure or flakiness rate.</p><p>For example, you can find answers to the following questions:</p><ul><li>What are the top failing tests in the suite?</li><li>Have the flakiness rate change in the last two weeks?</li><li>Show me the flakiest tests from the last 30 days for the main branch?</li><li>What is the average run duration? How did it change during the last 3 months?</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*dYy4p6AiMy4pAq3z" /><figcaption><em>Cypress Dashboard — Analytics Overview</em></figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*cm1TiBv2ETqHvs0Y" /><figcaption><em>Currents — Insights: runs status and more</em></figcaption></figure><p>When it comes to Analytics and Reporting, Sorry Cypress does not have any of the analytics and reporting features, but Cypress Dashboard and Currents have some interesting analytics and reporting capabilities.</p><p>Comparing between two — Cypress Dashboard provides more filtering options (e.g. filter by cypress runner version), while Current provides explicit and easy-to-use tools for exploring the insights (e.g. flakiest tests, top failing tests, runs duration etc.)</p><h3>Pricing: Cypress Dashboard vs. Sorry Cypress vs. Currents</h3><h3>Sorry Cypress Pricing</h3><p>The Sorry Cypress is free software that allows unlimited parallelization, recording, and debugging. The associated costs are:</p><ul><li>Cloud infrastructure costs (varies based on usage/provider)</li><li>Maintenance and support cost</li></ul><h3>Cypress Dashboard Pricing</h3><p>The Cypress Dashboard has 4 tiers that vary by available features and the number of users. Within those plans, the actual monthly charge depends on the number of tests recorded during a month.</p><h4>Free Plan</h4><p>Its free plan provides access to limited features, only 3 members and a limit of 500 test records per month.</p><h4>Team Plan</h4><p>The Teams plan starts at $75 per month, designed to use it with a small number of users. You can invite up to ten users.</p><h4>Business Plan</h4><p>The business plan costs starting $300 per month and allows up to 40 users. Apart from everything included in the Teams plan, the Business plan includes the following features.</p><ul><li>Smart Orchestration (Run failed specs first, Cancel run on failure)</li><li>GitHub Enterprise</li><li>GitLab for Enterprise</li><li>SSO</li><li>Email Support</li></ul><h4>Enterprise Plan</h4><p>If you want the Cypress Dashboard unlimited number of users and more than 300K monthly test results, you will need to switch to an enterprise plan. It includes every feature from the business plan plus:</p><ul><li>Unlimited test records</li><li>Unlimited users</li><li>Premium support</li></ul><h3>Currents Pricing</h3><p>Currents has a flexible pricing structure — the plans are based on the number of test results per month and the team size. Its plans start at $40 per month that provides up to 10K test results and access to up to 10 team members.</p><p>These various plans match organizations with different test volumes and number of team members. Also, the price is up to 86% lower compared to Cypress Dashboard.</p><p>All plans include all of the Currents’ features.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*q2-fk1FnEnolH3Iv" /><figcaption><em>Currents Pricing</em></figcaption></figure><h3>Unit Economics of Cypress Tests</h3><p>Let’s compare the pricing plans between the two paid solutions: Cypress Dashboard and Currents. We’ll scale down to the resolution of 1K test recordings and compare between different plans and volumes.</p><p>To summarize:</p><ul><li>Currents is on average 49.93% (almost x2) cheaper compared to Cypress Team plan</li><li>Currents is on average 66.9% (more than twice) cheaper compared to Cypress Business plan</li></ul><p>Cypress Dashboard Business plan is priced relatively high ($10-$30 / 1K tests) for lower (up to 50K) volumes. It is clear that the Business plan is built for customers with a higher amount of tests, also the Business plan unlocks access to all the tools.</p><p>Currents includes all the features even at the lowest cost option.</p><p>Sorry Cypress is the cheapest option and the only associated costs are maintenance and infrastructure, it was not included in the pricing comparison.</p><h3>CI Providers, Compatibility and Support</h3><p>All 3 dashboards are fully compatible with cypress and allow running cypress tests in parallel on popular CI providers like:</p><ul><li>CircleCI</li><li>GitHub Actions</li><li>GitLab CI</li><li>AWS CodeBuild</li><li>Azure Pipelines</li><li>and many more</li></ul><p>There’s a little effort required to start using cypress with Sorry Cypress and Currents — both services provide lightweight npm packages that enable seamless integration with cypress runners without affecting its functionality.</p><p>While all 3 tools work smoothly in CI headless mode (via cypress run ...), only Cypress Dashboard has native integration with Cypress runner interactive UI. Currents and Sorry Cypress are not integrated with the interactive UI, and do not provide the same native experience compared to Cypress Dashboard.</p><h3>Conclusion</h3><p>Currents, Cypress Dashboard and Sorry Cypress are alternative solutions for scaling up and managing end-to-end Cypress tests suite. We’ve compared the products in terms of parallelization and orchestration, debugging and troubleshooting, analytics and reporting, environmental and build information, integrations, and pricing.</p><p>Sorry Cypress is a self-hosted solution, that is also the cheapest, but is limited in features and requires an experienced team of DevOps professionals to maintain.</p><p>Currents has 90%+ parity compared to Cypress Dashboard, is easy to setup and is 100% compatible with cypress runner. It provides a few additional tools that are not present in the original Cypress Dashboard like: REST API, HTTP Webhooks, enhanced analytics and reporting. Currents pricing is x2-x2.5 lower compared to Cypress Dashboard — all users have access to all the features, regardless of the selected plan.</p><p>Cypress Dashboard is the original, mainstream and well-known service that natively integrates with the open-source cypress runner and is being widely used. Customers will have to pay an extra premium for using the original dashboard and getting access to all the features.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6c10ae553fdd" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Learn by Contributing]]></title>
            <link>https://yc.prosetech.com/learn-by-contributing-2434bdf53b06?source=rss-1bb5b7a41f59------2</link>
            <guid isPermaLink="false">https://medium.com/p/2434bdf53b06</guid>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[professional-development]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[career-advice]]></category>
            <dc:creator><![CDATA[Andrew Goldis]]></dc:creator>
            <pubDate>Sun, 21 Apr 2019 18:46:18 GMT</pubDate>
            <atom:updated>2020-03-09T14:48:48.041Z</atom:updated>
            <cc:license>http://creativecommons.org/licenses/by/4.0/</cc:license>
            <content:encoded><![CDATA[<h4>Contributing to open source is good for you and your career. Here’s how to get started.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3hZVew8ASYYZ2ps8abkbXA.jpeg" /><figcaption>Picture <a href="https://unsplash.com/photos/MAgPyHRO0AA?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Hello I’m Nik</a> on <a href="https://unsplash.com/?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>Being a professional software developer requires continuous improvement and learning. It doesn’t matter if you’re a boot camp or university graduate or a software development veteran, it’s useful for your own professional development (and curiosity) to explore different approaches to making software.</p><p>Keeping up the pace is difficult — you have to be aware of new technologies and get some experience with them, improve your expertise with mainstream popular tools, and evolve “vertically” by solving increasingly complex and abstract problems.</p><p>Experienced developers are limited by the tech stack used by the team at their workplace. Being aware of different approaches would give them leverage and show a different perspective on the solutions that are common in their team/company and the alternatives.</p><p>For developers at the beginning of their career path, it’s even more challenging. The variety of tools and techniques is overwhelming! It’s very hard to know what to focus on and what tool is best for a specific task without prior experience with a similar kind of a problem.</p><p>Courses and tutorials — even advanced ones — usually don’t provide the required level of confidence. There’s always a “beyond the tutorial” wall. You stumble upon a problem that is out of tutorial’s scope, and you need start looking for solutions elsewhere.</p><h3>How to grow with open source</h3><p>My main background is web development, and this specific niche of software development has undergone tremendous changes during the last years. There’s a well-known phenomenon of “Javascript fatigue” caused by the number of new tools and techniques that emerge every week. The language itself has changed a lot and became the most popular programming language on the planet.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/728/1*IW3keGjTN30klx0cIRyu-w.png" /><figcaption><a href="https://insights.stackoverflow.com/survey/2019#technology-_-programming-scripting-and-markup-languages">Stackoverflow Developers Survey 2019 — Most Popular Technologies</a></figcaption></figure><p>In this post, I want to share the technique of using open source projects for professional development that I’ve been practicing during the last few years. This technique works particularly well in the Javascript ecosystem, because of its particularly strong foundation in OSS.</p><p>Contributing to open source is good for you. Actually, it is good for everyone, and here’s why:</p><p><strong>You help others</strong></p><p>No matter what your contribution type is — documentation, code changes or even just opening an issue — you improve the tools we all use and make other developers life easier.</p><p><strong>Excellent project quality</strong></p><p>Open source software is not an underdog anymore. The quality of code is often superb to internal codebases. By working on projects of such quality, you see how others make good software.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/726/1*KBVRx3sRtfoeqkLyJxn_YA.png" /><figcaption><a href="https://insights.stackoverflow.com/survey/2019#work-_-quality-of-open-source-software">Stackoverflow open source projects quality — survey 2019</a></figcaption></figure><p><strong>Glimpse into professional software development</strong></p><p>You can literally see and learn how software is done at Microsoft, Google or Facebook (and many other companies are known for good engineering)— the companies share internally written code under open source license.</p><p><strong>Collaborate with experts</strong></p><p>It takes quite a lot of experience and expertise to recognize, implement and maintain a successful software project.</p><p>People behind these tools have a passion for their creations and love what they do — they are true experts. The feedback you’re getting while working with them is valuable.</p><p><strong>You’re creating proof of your expertise</strong></p><p>Having an impressive portfolio on Github (or whatever platform of your choice) is a solid indicator for your future employer. Moreover, many headhunters use Github to find talents.</p><p>Many companies hire core contributors that work on company-supported open source projects.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/644/1*QK1oCMjpVD-kaETwiPjffg.png" /><figcaption>Andrew Clark tweets about being hired by Facebook. Andrew contributed a lot to ReactJS eco-system prior to this tweet. <a href="https://twitter.com/acdlite/status/769272685209669632">https://twitter.com/acdlite/status/769272685209669632</a></figcaption></figure><p>Some companies sponsor maintainers of open source project without hiring them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fhX_78fllNwa06GYgRPeAg.png" /><figcaption>Example of maintainers being paid for their support of BabelJS via Open Collective. <a href="https://opencollective.com/babel#budget">https://opencollective.com/babel#budget</a></figcaption></figure><p><strong>It’s free</strong></p><p>Education and experience are expensive. While engaging and contributing to open source projects, you’re getting valuable experience of practicing software development, getting feedback, and creating a portfolio for free!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/706/1*FPvISPq_vozg5asOnqFFFw.png" /><figcaption><a href="https://insights.stackoverflow.com/survey/2019#developer-profile-_-other-types-of-education">Stackoverflow informal education types — survey 2019</a></figcaption></figure><p>Now that we’ve agreed that contributing is awesome, let’s try to break down the types of contribution you can do, depending on your time, required effort and expertise in the subject.</p><h3><strong>Every time you face a problem</strong></h3><p>It’s hard to start contributing without any context or specific motivation. How do you pick a project that is interesting enough and would be useful for your professional development?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/780/1*UdOUexsbTSD0dL8uXLinjQ.png" /><figcaption><a href="https://insights.stackoverflow.com/survey/2019#developer-profile-_-contributing-to-open-source">Stackoverflow open source contribution rates — 2019</a></figcaption></figure><p>It’s much easier to start when you have an actual problem with a third-party open source project. A problem that matters to you.</p><p>Fortunately, Javascript development is very dependent on publicly available software (via npm packages) and the solutions are not perfect. Every time you see a problem — either it is a configuration, documentation or an actual issue, it’s an opportunity to improve, contribute, learn, and boost your professionalism!</p><h3>The contribution checklist</h3><h4>Create an issue</h4><p>That’s the minimal, least time-consuming and most important type of contribution you can do.</p><p>One can say it is not a real contribution, but I do consider it very important. In fact, Github counts it as a contribution:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/582/1*VaWdY8grXqENUij___ZBVw.png" /><figcaption>The 4 types of contribution as considered by Github</figcaption></figure><p>Let’s start with an obvious observation — without creating an issue, maintainers would never know there’s a problem with their software, neither they would be able to improve it.</p><p>But, you’re the one who mostly benefits from doing that!</p><p>Have you ever found yourself trying to unsuccessfully solve a problem, and after a few attempts calling a colleague for help? As soon as you start to describe the problem — eureka!</p><p>You’ve suddenly got it! (Usually, it’s a typo, right?)</p><p>It is quite hard to describe a problem effectively and precisely ✍🏻. Most projects today use some kind of a template for new issues. By following the template, you’re forcing yourself to look at the problem from a different point of view.</p><p>By describing the problem in your own words, you can suddenly realize what the solution is and… just apply it. Alternatively, describing the problem in your own words could spark new ideas/hypothesis. If that’s the case — 🙌🏻 great job—go ahead and tell your colleagues.</p><p>If not, you’ve just created an issue with a good explanation. It would help the maintainers. You helped other developer — now they are able to find the problem and realize that it is an issue with their own code. People will discover your issue and add 👍🏻</p><p>By having this first engagement you create an opportunity for the maintainers to guide you, possibly propose a solution and motivate you to open a pull request with a fix (more on that later).</p><p>See, you’re already helping lots of people!</p><p><em>Bonus</em>: When creating an issue on Github, you get a nice auto-suggested list of already existing issues, that help to discover a solution and prevents duplications. 👍🏻</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/816/1*6anaOuvbyECKT93W6CBNtA.gif" /><figcaption>Github auto-suggests similar issues</figcaption></figure><h4>Provide a minimal example</h4><p>It would be much easier for the maintainers to deal with a very specific, minimal representation of the issue you’re reporting.</p><p>Although it is more time-consuming, it is also beneficial for you. By extracting the problem you get:</p><ul><li>Confirmation that it is actually a problem with the tool/library itself and not with your own code</li><li>A better understanding of what the problem is (which can be used later to effectively describe the issue)</li><li>Opportunity to solve the problem by dealing with a simplified context</li></ul><p>By removing unnecessary complexity while composing a minimal example, there’s a high chance that you understand the problem better, discover a solution or even realize that it wasn’t a problem at all 😼!</p><p>Here’s a list of some platforms that can be used to create a reproducible example:</p><ul><li>A new repository on Github</li><li><a href="https://codesandbox.io/">Codesandbox</a></li><li><a href="https://jsfiddle.net/">JSFiddle</a></li><li><a href="https://codepen.io/">Codepen</a></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zd68OIMpg_a8Q4bqN7ShoA.gif" /><figcaption>Example of a dedicated repository with a reproducible issue. <a href="https://github.com/babel/babel/issues/9853">https://github.com/babel/babel/issues/9853</a></figcaption></figure><h4>Find a workaround</h4><p>At this stage the problem is confirmed and validated, or maybe not completely validated, but… you want to move forward and just get rid of it!</p><p>Odds are that you don’t have time to dig into the third-party library source code, but you can definitely find a workaround. It could be an ugly monkey-patching, configuration change or some creative way you’ve found to overcome the problem. It is your obligation to share it with the world!</p><p>Either create a new issue or add a comment. You’ll get tons of ❤️ , 👍🏻 and 🎉</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/843/1*_omXtwYpc9D517KeoGiiLg.png" /><figcaption>Workaround and a lot of👍🏻 example</figcaption></figure><p><em>Bonus</em>: other people could comment and share a workaround that’s better than yours.</p><h4>Suggest a solution in comments</h4><p>Great news — you’ve just found a solution or have great confidence about what might be a good solution!</p><p>It works great in your codebase, but you don’t have time to create a pull request with tests and /or documentation. It still might be valuable to just share your discovery, because others will pick it where you left.</p><p>Often the problem is not even in the code — it might be a configuration issue or lack of clear documentation that leads projects users in a wrong direction. The point is to share this little piece of knowledge — it is valuable, even if it doesn’t seem like significant contribution.</p><h4>Implement a solution in your own repository</h4><p>What often happens that project maintainers are not responsive. Most of the time they are just busy with their life, or too busy at a workplace.</p><p>A good temporary solution might be forking the project and pushing the change in your own repository. Your peers can use your temporary repository as a dependency. While not ideal, it can help your team to move forward. ✅</p><p>Meanwhile, submit your fix as a PR. Eventually, the authors will review your fix and issue a new release. It is very important to create the PR though, otherwise, you’re at risk of being stuck with a dependency that cannot be updated.</p><p>Sometimes, authors will suggest joining core contributors’ list, and that’s awesome — you have the opportunity to take the responsibility and maintain a project with active users.</p><h4>Create a pull request</h4><p>Pull requests are the bread and butter of open source development.</p><p>Everyone can contribute, take part in a bigger project, leave a digital trace of skill and expertise 🌟.</p><p>Most important — it is the biggest, most effective opportunity for an individual to learn and improve 💪🏻.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/245/1*oOhZvqsZn4qOwcJ6janqjQ.gif" /><figcaption>Contributing to open source projects gives you superpowers and helps humanity</figcaption></figure><p>There’re several layers of valuable experience you gain by submitting a pull request — let’s list them:</p><ol><li>You see how complex problems are solved, discover new architectural approaches, different ways to organize project and code</li><li>You discover new coding styles and techniques</li><li>You discover the new or different application of testing frameworks, CI pipeline, linters and enrich your experience and knowledge of using other complementary tools</li><li>You are creating an opportunity to get valuable feedback from experienced professionals</li><li>You are getting knowledge about the internal implementation of the tool you’re working on — it will help you to use it better</li><li>You’re creating an authentic, transparent record of your achievements and professionalism.</li><li>You connect with other developers, which creates opportunities for collaboration, hiring and is simply fun</li></ol><p>That’s how you learn and become a better professional — you do more of different stuff.</p><p>You see and try different approaches, learn the good and the bad parts, apply what you’ve seen in different situations and get feedback about your decisions.</p><p>By iterating and regularly challenging yourself with more complex subjects you gain the professional confidence and experience 🥋</p><h3>Discovering opportunities to contribute</h3><p>As I have mentioned, it is easier to start to contribute when you have an actual issue in you have to resolve. But what should you do if you don’t work with OSS tools and still want to find contribution opportunities?</p><h4>Online</h4><p>Github <a href="https://help.github.com/en/articles/helping-new-contributors-find-your-project-with-labels">recommends</a> project owners to assign labels to issues that are easier to start with. A simple <a href="https://github.com/search?q=label%3A+good+first+issue">search</a> by label: good first issue will reveal more than 200k issues to pick from 😄</p><p>You use label: help wanted <a href="https://github.com/search?q=label%3A+help+wanted">search query</a> to discover more complex issues that are not necessarily beginners-friendly.</p><p>There’re plenty of resources that do some kind of aggregation based on technology, difficulty, and popularity of a project.</p><p>Here’s a list of few such projects to get you started:</p><ul><li><a href="https://github.com/MunGell/awesome-for-beginners">Awesome list for beginners</a> — a curated list of projects categorized by tech stack</li><li><a href="http://github-help-wanted.com/">http://github-help-wanted.com</a> — “help wanted” issues aggregator</li><li><a href="https://www.firsttimersonly.com/">https://www.firsttimersonly.com</a> — a list of useful reads for newcomers to open source</li><li><a href="https://giistr.com/">https://giistr.com/</a> — search, filter and help easily on the issues of the repositories you starred</li><li><a href="https://www.codetriage.com/">https://www.codetriage.com/</a> — pick your favourite repos to receive a different open issue in your inbox every day</li><li><a href="http://issuehub.io/">http://issuehub.io/</a> — issues aggregator by tech and difficulty labels</li><li><a href="http://www.pullrequestroulette.com/">http://www.pullrequestroulette.com/</a> — a list of pull requests (or PRs) submitted for review, belonging to open-source projects</li></ul><p>And a lot, a lot more…</p><h4>Offline</h4><p>There’s a good chance more people in your area are interested in open source contribution opportunities. Try to find a meetup event.</p><p>One particular example I want to highlight is a <a href="https://hackernoon.com/goodness-squad-a8704d594a7a">Goodness Squad</a>. I personally participated in one of those events a few years ago and it was extremely effective and helpful for me.</p><h3>Summary</h3><p>While writing the article and discussing it with my friends we noticed that there are plenty of resources to find projects that need contributors help. However, it is quite hard to find a project that you can learn a particular skill / coding aspect.</p><p>That’s why I have decided to try and create an alpha version of such a list:</p><p><a href="https://github.com/agoldis/learn-by-contributing">agoldis/learn-by-contributing</a></p><p>This is a small list of projects that I personally found helpful for my own professional development (Javascript-related only for now). I hope it is a good start for a place developers can find good projects that they can learn from.</p><p><em>The article was originally published at: </em><a href="https://dev.to/agoldis/learn-by-contributing-27g6"><em>https://dev.to/agoldis/learn-by-contributing-27g6</em></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2434bdf53b06" width="1" height="1" alt=""><hr><p><a href="https://yc.prosetech.com/learn-by-contributing-2434bdf53b06">Learn by Contributing</a> was originally published in <a href="https://yc.prosetech.com/">Young Coder</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why I quit Amazon just 5 months after I’ve started]]></title>
            <link>https://agoldis.medium.com/why-i-quit-amazon-just-5-months-after-ive-started-4ce872520f02?source=rss-1bb5b7a41f59------2</link>
            <guid isPermaLink="false">https://medium.com/p/4ce872520f02</guid>
            <category><![CDATA[amazon]]></category>
            <category><![CDATA[interview]]></category>
            <category><![CDATA[employment]]></category>
            <category><![CDATA[employees]]></category>
            <category><![CDATA[experience]]></category>
            <dc:creator><![CDATA[Andrew Goldis]]></dc:creator>
            <pubDate>Mon, 05 Nov 2018 01:04:55 GMT</pubDate>
            <atom:updated>2019-06-29T05:16:51.277Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*85kshtocmc5EjYCK1rYqhw.jpeg" /><figcaption>Sad character reminds me of myself hoping to have good times as Amazon employee</figcaption></figure><p>I started to work for Amazon on January 28, 2018 — that was about three weeks after I, my lovely wife and our cat landed at Vancouver International Airport. At the time of arrival our biggest concern was the cat — 18 hours flight from Tel Aviv to Vancouver was quite a challenge for all living creatures.</p><p>The cat was ok, in fact he recovered fast and started to explore the AirBnB apartment we rented. Vancouver was, as expected, rainy and foggy, but very picturesque and different from the sunny and vibrant Tel Aviv. We were quite excited — we spent last 6 months in preparations for the move and finally it happened.</p><h4>How I was hired</h4><p>It all started in June 2017, at this time I was working for Rollout.io — a small start-up company, and it was about the time I started to feel I need some change. I did have 6 years of experience working for Intel Corporation, I knew what is it like to work for enterprise, I didn’t like it. Nevertheless, I decided to apply for a job at Amazon Vancouver as part of a big hiring event that was organized by the company in Tel Aviv. It sounded like a great adventure and exactly the change I needed.</p><p>The hiring process was very standard:</p><ul><li>online coding challenge — algorithmic questions similar to what you find online on … coding challenge sites (easy, no preparation)</li><li>phone screening with an HR person — closed questions about CS basics: BigO notations, algorithms names, terms (easy, no preparation)</li><li>face-to-face interview — see details below</li></ul><p>I was notified that I passed remote screening and scheduled a face-to-face interview, I started to take the application seriously — for about 3 weeks, every evening, I spent about 2 hours practicing CS trivia questions. I used “<a href="https://amzn.to/2Ls9Zh4">Cracking the Code Interview</a>” — the book turned to be useful, but I hated it. It felt wrong and time consuming. I knew I would never need this knowledge.</p><p>I graduated CS-ish faculty from a considerable academic institution — while studying I did see very smart people not being good with walking trees and calculating big-O’s. While working at the other companies, I have seen people without an academic degree being brilliant, successful engineers. I did tons of interviews (as an interviewer) while working for Intel and Rollout and I vote <a href="https://medium.freecodecamp.org/why-is-hiring-broken-it-starts-at-the-whiteboard-34b088e5a5db">strongly against whiteboard interviews</a>, but I decided to play the game.</p><p>I read 3–4 articles of ex-amazonians about their hiring experience and the interview process. Based on my experience I felt like I was well prepared.</p><p>During the interview day I met 4 Amazon employees — it all went exactly as expected — algorithmic question, systems design, architectural design, data structures questions — no surprises, questions were not too difficult. The people were polite and official. One guy was tough. Every interviewer asked 1–2 behavioural questions.</p><p>Two weeks later I got an email with good news. During the first Skype conversation I was told that I am qualified for SDE1 role, I didn’t really know what that mean. Quick search showed me that it is “<a href="https://www.quora.com/I%E2%80%99ve-had-some-unprofessional-and-negative-experiences-with-a-recruiter-from-Amazon-Is-Amazons-recruiting-getting-sloppy-or-is-it-just-this-one-recruiter-Should-can-I-report-them-to-someone">college graduate</a>” level — pity. I have about 10 years of experience in industry, but ok, may be I could do better at the interview. I swallowed my ego and decided to disregard the title, if I am as good as I think, people should recognize it and would be promoted quickly, right?</p><p>The recruiter explained me about the relocation process, we didn’t talk about compensation. <strong>The recruiter didn’t show up for the next scheduled Skype call</strong>, I didn’t get any email or explanation. (that’s quite <a href="https://www.quora.com/I%E2%80%99ve-had-some-unprofessional-and-negative-experiences-with-a-recruiter-from-Amazon-Is-Amazons-recruiting-getting-sloppy-or-is-it-just-this-one-recruiter-Should-can-I-report-them-to-someone">common</a> for Amazon recruiters).</p><p>Two weeks later I was contacted by another recruiter and she picked up the process where we left. We started to negotiate — the initial proposal was too bad. I checked the average of compensations reported at <a href="https://www.glassdoor.ca/Reviews/Amazon-Vancouver-Reviews-EI_IE6036.0,6_IL.7,16_IM972.htm?countryRedirect=true">Glassdoor</a> and other sources and built my strategy for the upcoming negotiation.</p><p>The recruiter mentioned policies that do not allow to exceed certain thresholds for a given role, she said there’s another team that approves the offer and she only communicates it to me.</p><p>3 rounds later I agreed to sign for 35% more than the original offer. 🎉</p><p><em>It was hard to negotiate — I did some homework, but still felt uncomfortable talking about money, the recruiter was a strong negotiator — I believe she has dozens of such conversations a day. Learn how to negotiate — it is important!</em></p><p>I asked what will I do as part of my job: who is the manager, how many people are in the team, what is the tech stack, what are the engineering practices.</p><p>The recruiter connected me to the hiring manager. I was finally able to get some information about the actual job — and that was the very first time I got <em>some </em>impression about what is the job about.<em> </em>It was Java-centric Amazon eCommerce Payments team. They had real-business projects, the tech stack was Java-based, CI, tests, code-reviews, team events… looks ok.</p><p>I signed the (virtual) papers.</p><h4>5 months at Amazon</h4><p>Besides overall excitement caused by moving to a new place, I was intrigued to join Amazon and to explore the company as an insider — it is one of the great tech giants, and I was wondering how does it look like.</p><p>I met very smart and talented people, I met good people at Amazon. They were brought by the company from all over the world — China, Argentina, Pakistan, Ukraine, Turkey, Russia, Israel, Vietnam, Hungary, Germany. Later I discovered that it is quite common for Vancouver (and seems like Canada’s metro-areas) to have such multi-cultural concentration of professionals.</p><p>I joined a team within Amazon Consumer Division — that is part of the company that’s responsible for its online shopping business (more or less). I’d love to share more details about the team itself, but I am not sure what are NDA limitations. I can say it was kind of classic old-school team with Java-centric “invented here” Amazon stack (internal set of tools for source code control, managing dependencies, CI and CD). There wasn’t any scary operational load or ugly legacy systems to support — i.e. it was quite a “sane” team.</p><p>I was overwhelmed by online “cultural” trainings about the company’s leadership principles and other corporate bullshit, I felt like I am joining a religious organization and being brainwashed.</p><p>Supposedly, every employee should be guided by the <a href="https://www.amazon.jobs/en/principles">leadership principles</a> during their day-to-day routine. The principles actually make a lot of sense, when used appropriately. As time went, I discovered that the most common application of the principles was <em>to creatively find a leadership principle that best supports</em> <em>the situation</em>.</p><ul><li>Wasn’t your ideas accepted by someone? <em>You have to earn trust.</em></li><li>Want to justify particular solution? <em>Show it supports customer-obsession principle.</em></li><li>Want to convince someone to do tedious work? <em>Insist on highest standards.</em></li><li>Want to round a corner? <em>Invent and simplify.</em></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/460/1*tsJR_TfQdmRge39pudcPeA.gif" /></figure><p>It took me some 1–1.5 months to start feeling comfortable with the environment. Teammates were helpful and friendly, management was demanding but friendly.</p><p>The team’s product was highly dependant on other services and was subjective to what is called in Amazon’s “away team” experience — that is when you need to change the source code of a service run by another team.</p><p>That was a terrible experience — the other teams neither had context nor motivation to support you, the proposed changes were pushed back, discussed in endless meetings with “bar raisers” and took extreeeeeeemly long.</p><p>I had some minor issues with the engineering practices (see my previous post). I was impressed and disappointed by the internal tools (CI, CD, build tools) because they were actually good, but not good enough comparing to current developers experience provided by modern SaaS companies.</p><p>I did see quite a lot of managerial effort aimed to create a good environment for developers — both mental and technical. I actually was surprised by the amount of time invested into “probing” team’s wellness. I didn’t stay in the company long enough to see the results of this process, both I didn’t like the methodological nature of it. I had a feeling that many of the processes were done because they need to be done, but not to achieve any result.</p><p>2 months later I could say that I became an active team player, I got some responsibilities, I worked pretty hard, the deadlines were challenging. I didn’t do a lot of coding. I would say time was distributed as follows:</p><ul><li>20% coding</li><li>50% collaborating — writing / reading documentation or emails + messenger conversations</li><li>30% meetings</li></ul><p>I think I could re-distribute my time, but given the fact that I wasn’t too efficient with Java (it was not the primary tool in my past experience) and had no Amazon-specific experience as other team members I found myself in this position.</p><p>My manager used to mention the term “amazonian way” while discussing the engineering practices and business decisions. I felt like the term is used to shut down an unwanted change or suppress an opinion when no real reason could be exposed.</p><p>It was challenging for me to deal with “tribalism” and “de-facto”-ism that I faced at Amazon, especially when communicating with the leading engineers. — senior software engineers and “bar raisers”— those are the guys that are trusted by the “tribe” to approve important design and architecture decisions, enforce company policies and be a role mode / authority with deep knowledge in specific domain.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*RQ40u5tcqhFF0qjRnyIG4A.gif" /></figure><p>My manager told me it is trust that I yet to earn — people don’t trust my judgement and I need to build good relationships with decision makers. I agreed. But that what is called “politics”. I felt a toxic culture creeping into my day-to-day routine — trying to cover your ass, trying to keep control, trying to only work on projects that contribute to your promotion, resisting to ideas, following processes blindly without being able to distinguish between important and non-important.</p><p>As time goes you start to to use the “art of fetching a principle” and see other people doing it in conflicting situations, trying to find one that supports your argument.</p><p>I did succeed to promote a couple of architectural and design solutions. It was important for me to feel impact of my job (I think it is important for every software development professional). However, it wasn’t enjoyable experience , it was painful— mostly mentally.</p><p>It was 4 months since the first day of my employment. I’ve got an impression that I have enough data to reflect on my experience at Amazon.</p><p>I talked to my peers and friends, I wanted to validate my observations. I was afraid to make a mistake — all-in-all the job was very convenient, there were quite a lot of RS units pending. In addition, I couldn’t legally have any other job because I was issued a work permit that was only valid for employment at Amazon,</p><p>5 months after my first day at office, I left the company.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/504/1*5hVDI1CgvGxiC-eyFrKlkA.gif" /></figure><p><strong>Leaving Amazon</strong></p><p>Here’s the summary of my observations that convinced me that Amazon (or at least the team I work at) is not a good place for me to stay</p><p><strong>The (lack of) tech challenges</strong></p><p>The major algorithmic / coding / intellectual challenges that I faced were of 3 types:</p><ul><li>dealing with technical debt of other systems</li><li>strictly following a policy or a standard</li><li>fighting with the in-house dev environment</li></ul><p>There were very few interesting problems that actually required to find an effective solution / optimize / enforce security. It would take me 3–4 years in order to reach the level of “trust” that would expose me to challenges of different scale and impact.</p><p><strong>Leadership</strong></p><p>I mentioned that I met a lot of talented and smart people at Amazon. However, people that were distinguishably “successful” and “important” for the organization — i.e. SDE3, “bar-raisers” and managers, weren’t as much “role-model” as I wanted.</p><p>Moreover, I saw quite a few senior engineers and discovered that I do not want to be alike… Either professionally incompetent, either political or arrogant — those people successfully managed to navigate their careers and be recognized by the company (and company’s culture) as leaders.</p><p>What does it say about the company?</p><p><strong>Stress and nonsense</strong></p><p>The 5 months at Amazon was the most stressful job I ever had. It came in many forms, some highlights from my personal experience:</p><ul><li>Pressure the management put on the team (which is applied on the management by their management). I mean not healthy pressure — e.g. reminders that it is your responsibility to finish a task, although you’re dependant on a 3rd party to do their job aka “away team” experience.</li><li>Semi-legal business trips to Seattle to close gaps and to speed up processes. The management expects you to be ready and spend your 6 hours of personal time driving to / from Seattle. Although legally you are only allowed to go US for trainings or meetings, however, you can find yourself driving (or taking a bus) to Seattle at 6pm Wed, working in a conference room during the next 2 days in order to meet a deadline. I have seen people doing that… The other day I was interrogated for 20 minutes by a border officer and was almost deported at US/Canada Border because I mistakenly stated that I go to work for Amazon at Seattle. I could be denied an entry to US for the next 5 years!</li><li>Endless policies that make no sense. The management has no problem sending employees to Vegas for AWS 4 days conference that would cost 5000 US$ / employee, but you’ll need to work hard to get an approval to spend extra 80$ for a good room for a business trip to Seattle.</li></ul><p><strong>Promotion</strong></p><p>When initially I decided to accept the job, I mentioned that I hoped to prove that I am good and to be promoted quickly. Sadly, that is not how it works.</p><p>You won’t be promoted for doing your job, you will be promoted by <strong>focusing on your promotion</strong>.</p><p>To get promoted from “junior engineer” (SDE1) to “an engineer” (SDE2), you get a “form” that lists what is needed to be promoted, e.g.:</p><ul><li>code enough</li><li>code well</li><li>do some support-related stuff</li><li>write some documentation etc.</li></ul><p>Unless you are mindful to have this form filled, groomed with good leadership principles, you won’t get a promotion.</p><p>It is not enough to get your job done and help the company grow.</p><p><em>Edit: I would like to clarify the statement above — by writing “get your job done” I mean: do your job in excellent manner, outperform, and what one of commenters phrased as “exceed expectations”. It wasn’t the right use of the term, so I feel the need to clarify. I don’t expect to be promoted “just” by doing your job. I want to be promoted by being extraordinarily good and helpful at doing my job. Not at writing promotional documents.</em></p><p>The promotion process from SDE2 to “senior engineer” is similar — you get a bigger form and you need to be lucky to:</p><ul><li>have a good manager</li><li>be a part of good projects</li><li>be promotion-oriented and to constantly improve the form</li><li>be political and have a good recommendations from peers (but not all peers — only those who matter)</li></ul><p>It is not different from other big companies, of course, and it is kind of industry standard, but I like the idea of being promoted because you are good and valuable to the company — the company compensate you in return with responsibility and benefits.</p><p><strong>Compensation</strong></p><p>This is a common issue for companies that provide RSU as part of their compensation, but what is more problematic and manipulative is how companies use RSUs to mislead employees about of their compensation package.</p><p>To be fair, all-in-all Amazon pays quite well, at least comparing to Vancouver metro area alternatives. <a href="https://money.cnn.com/2018/04/30/technology/google-median-salary-rank-facebook-amazon-apple/index.html">Not as well as other big tech companies</a>.</p><p>For example, let’s say you are offered 150k total compensation. The composition is:</p><ul><li>110k base salary (that is what counts as your income for most financial topics — e.g. mortgage, banking privileges etc.). Note, that when you get an employment verification letter — that’s what appears as your income level. That is the promised income you get from the company.</li><li>25k signup bonus — that’s how a company will lure you into the contract. It is important to realize that bonuses are taxed differently, in my case I could see only about 50% of the bonus in my bank account. Sadly I discovered that too late. <em>Update March 2019: as one of blog readers pointed out: “…bonuses are taxed as income — they are taxed the same. It’s just that it’s based on what they estimate you’ll make at the end of the year. That is, you’ll get your bonus money when tax return comes.”</em></li><li>15k RSU paid at the end of the first employment year. The idea is share company’s success (which is supposedly expressed by stock price) with an employee, making him work harder to make the company successful. In reality in such a huge companies no employee has any effect on company’s success, and the stock is highly affected by global trends or politics. At the time of writing this post AMZN was selling for as low as 1598 USD. At the time I was proposed the contract, the valuation was around 1650 USD. So, effectively, a company would not meet the promised 150k / year. In most cases stock price would go up, but then at the next performance review you will be told “Hey, your total compensation is 190k — looks at the stock price, so we’ll increase the “base salary” only by 3% to match the inflation growth”. How would your boss or recruiter respond if you’d say “I would work approximately full time job, may be”. Moreover, the more you stay at the company, the more your income composition is based on RSU. It works pretty well for the majority of the industry, as well as for Amazon. That’s industry standard, and I think it is manipulative and misleading.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/500/1*HlZL-ZCao0Tfmw8Nu-trjQ.gif" /></figure><h3><strong>Summary</strong></h3><p>There are a lot of happy and satisfied Amazon employees, there are a lot of smart, talented and good people I respect and love that I met while working at Amazon.</p><p>The company is so huge that it’s hard to manage it without having strict policies and well-defined processes. I don’t know whether my experience is applicable to the rest of the company to other teams within the company.</p><p>Probably I am just not kind of a person (well, at least for now) that fits the company’s culture. But I do want to write down my observation in hope, possibly, to help others build the right expectations before joining Amazon as a software engineer.</p><p>May be later in my life I will change, and reconsider this article, may be another team within Amazon would be a good fit for me, but for now I consider Amazon as a great and unique business, but just an average place to work at.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4ce872520f02" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Face uncertainty by decoupling Redux state]]></title>
            <link>https://agoldis.medium.com/decouple-redux-state-875c8367350f?source=rss-1bb5b7a41f59------2</link>
            <guid isPermaLink="false">https://medium.com/p/875c8367350f</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[redux]]></category>
            <category><![CDATA[decouple]]></category>
            <category><![CDATA[reactjs]]></category>
            <category><![CDATA[state]]></category>
            <dc:creator><![CDATA[Andrew Goldis]]></dc:creator>
            <pubDate>Sun, 29 Apr 2018 02:35:30 GMT</pubDate>
            <atom:updated>2018-04-29T03:47:59.444Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0e6fFQQRvkZ1LkeAHAMx7w.jpeg" /><figcaption>Photo by <a href="https://unsplash.com/photos/-K6JMRMj4x4?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Florian Klauer</a> on <a href="https://unsplash.com/photos/osSryggkso4?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>Redux is one of the most widely-adopted and used tools today. Indeed, the idea of using a single state tree and simple, trackable flow of events through reducers was easy to understand and debug.</p><p>However, developers find it annoying to deal with relatively high amount of boilerplate, and as always, when you go beyond the basic concepts described in tutorials and demos, things start to look scary and complex.</p><p>Redux creator Dan Abramov <a href="https://medium.com/@dan_abramov/you-might-not-need-redux-be46360cf367">mentioned</a> that not every application actually requires Redux, and many can manage without explicit state management tool or by using alternatives. Moreover, there are <a href="https://react-etc.net/entry/rip-redux-dan-abramov-announces-future-fetcher">speculations</a> about a new type of state management tool coming soon.</p><p>In reality, there are many applications that are already invested in Redux. Moreover, if Redux is a good fit for big applications, how do we manage the complexity of facing changes and evolution of such apps effectively?</p><p>In this post I will try to show how decoupling and encapsulating Redux state can help us to deal with unpredicted changes while keeping components simple and allow easy testability for app components and data layer.</p><h3>Motivation</h3><p><em>If you are already motivated enough to have your state tree decoupled and encapsulated, skip this part and go to the next chapter.</em></p><p>When all the requirements are well-defined in advance, it might be clear and easy to build the state tree, but what if things are not clear from the very beginning? What if you are gradually creating UI and the next feature is still not clear? What if you are not sure about the shape of the state? Will you use ImmutableJS or reselect, will your state be normalized?</p><p>Uncertainty doesn’t allow us to plan and implement ideal state, so most chances it will change in future — and we should be prepared.</p><p><strong>State tree shape can change</strong></p><p>It is annoying to change mapStateToProps every time you decide to move or rename some part of state tree. The change would require refactoring of every component that consumes the changed part of the state.</p><p>Consider the following example, you start with a simple state tree, which has users and tasks lists, e.g.:</p><pre>{<br>  users: [{ id: &quot;user01&quot;, name: &quot;John&quot; }, { id: &quot;user02&quot;, name: &quot;Bob&quot; }],<br>  tasks: [{ id: &quot;task01&quot;, title: &quot;Wash car&quot;, assignee: &quot;user01&quot; }]<br>}</pre><p>You have 3 views, each consumes some part of the tree:</p><ul><li>Users — lists all users, consumes users from redux state, it expects to get an array of users in its props: props.user = [...]</li><li>Tasks — lists all tasks, consumes tasks from redux state, it expects to get an arrays of tests in props: props.tasks = [...]</li><li>TasksByUser — lists all tasks by a user, consumes users and tasks from the state and expects to receive list of users with their tasks included: props.userTasks = [{ id:..., tasks: []}, ...]</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*vSE29fKyoY_9dqL4xOIqEQ.png" /></figure><p>Sweet! Now let’s say you’ve decided to add a new top-level brach ui — people <a href="https://redux.js.org/faq/organizing-state#organizing-state-only-redux-state">say it might be good</a> to keep local components’ state in redux.</p><p>We don’t know what additional global branches we’ll need (may be env?), so we decide to scope all “business”-related state under app.</p><p>Our state tree now looks:</p><pre>{<br>  app: {<br>    users: [...],<br>    tasks: [...]</pre><pre>  },</pre><pre>  ui: { ... }<br>}</pre><p>Can you smell the problem? All the views require refactoring — 👎🏻.</p><p><strong>State tree entities structure can change</strong></p><p>Next challenge! Let’s follow the best practices and have our state <a href="https://redux.js.org/recipes/structuring-reducers/normalizing-state-shape">normalized</a>. The new state would have the next structure:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/81a8767da4779a33920d4c44a04379f9/href">https://medium.com/media/81a8767da4779a33920d4c44a04379f9/href</a></iframe><p>Notice that we have changed users and tasks branches — the entities are replaced with keyed objects {}, instead of arrays [].</p><p>The components have to be refactored again! We need to rewrite mapStateToProps in each component (again) in order to deal with the new format of the data — 👎🏻.</p><p><strong>More motivation</strong></p><p>Eventually you’ll add more components — they will represent new state entities, or relations between state entities. You’ll want, though, to keep your state “minimal”. That means that only essential data lives in the state tree — all other derived pieces of information will be calculated based on the minimal state, and recalculated when the minimal state is changed.</p><p>The classic example is to have a visibilityFilter and items as part of the minimal state, while visibleItems are derived every time the related fields of the minimal tree are changed.</p><p>That approach prevents duplication of data and makes your data layer “reactive” in the manner similar to ReactJS components.</p><p>Libraries like <a href="https://github.com/reactjs/reselect">reselect</a> (or <a href="https://github.com/toomuchdesign/re-reselect">re-select</a>) will help you to create pure memoized functions for computing the derived state automatically and efficiently.</p><p>You need to manage the derived state efficiently — maximize code reuse, allow testability and easy management.</p><p><strong>Even more motivation</strong></p><p>When connecting our state to a component, we extract different fragments of state tree to compose a convenient data representation (either in mapStateToProps or in render ). If you find yourself in such a situation — most chances this logic should be extracted from the component and be part of “derived” state.</p><p>Your components should be agnostic to implementation details of the state — mapStateToProps just receives state and extracts slices that are required for rendering. The component shouldn’t know whether it is a derived data or part of the minimal state.</p><p>Moreover, ideally, you would never want to modify mapStateToProps due to a change of state shape or adding convenience / management tools.</p><p>By doing that we prevent duplication of functionality and keep components “dumb”, simple, modular and elegant.</p><p>Are we motivated yet?</p><h3>Expecting changes</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/400/1*Ym_T8LalbQfqrog4B5xq8Q.gif" /><figcaption>Dealing with uncertainty</figcaption></figure><p>Let’s see how can we can use some techniques to easily modify state and keep the complexity related to data management out of components.</p><p>As example, consider an application with the following entities in the tree:</p><ul><li>users — list of users with nested list of books read</li><li>books — list of books</li><li>comments — list of user comments for a book</li></ul><p>The application has the next views, which are implemented in React components accordingly:</p><ul><li>AllUsers — list of all users with short summary of comments and books</li><li>AllBooks — list of all books with a shoer summary of readers and comments</li><li>UserDetails — single users details with a detailed list of all books read and user’s comments for each book</li><li>BookDetails — single book detailed view with a detailed list of readers and comments</li></ul><blockquote>The source code of the app used for demonstration is available at <a href="https://github.com/agoldis/decouple-redux-state">https://github.com/agoldis/decouple-redux-state</a>. The repository has several branches that contain changes I am applying to the code.</blockquote><blockquote>There could be many implementations for this application. The particular implementation I suggest aimed to display the decoupling techniques. I assume my intelligent reader will apply the example on bigger real applications.</blockquote><p>We need to compose different entities of the state in order to create proper data structures for convenient rendering of the views.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/633/1*qv-2JG2AWOpvCW9yIgeDTw.gif" /><figcaption>Preview of the sample application <a href="https://github.com/agoldis/decouple-redux-state/tree/01-initial-project">https://github.com/agoldis/decouple-redux-state/tree/01-initial-project</a></figcaption></figure><p><em>Check out this branch to examine the application </em><a href="https://github.com/agoldis/decouple-redux-state/tree/01-initial-project"><em>https://github.com/agoldis/decouple-redux-state/tree/01-initial-project</em></a></p><p>Each component defines its own mapStateToProps method and uses react-redux&#39;s connect utility to get updates. I am listing the implementation of each such method — you can see that different components require different representation of the state, combining its pieces to get a convenient structure.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/d5fa46d8b6a1cf087221fb4252de3d56/href">https://medium.com/media/d5fa46d8b6a1cf087221fb4252de3d56/href</a></iframe><p>For this simple application it’s not a problem to keep these mapStateToProps together with the components, but remember that we are preparing for changes — and even a small state structure change would require a lot of refactoring; when application grows, we may end up having many components and much more refactoring.</p><p>Obviously, we’d want to extract the logic defined in mapStateToProps. But how to make it available to all components? May be, we’ll just move it to the state itself?</p><p>Let’s look closer how do we creating a store — the method createStore accepts the following arguments:</p><p>createStore(reducer, [preloadedState], [enhancer])</p><p>We’ll use the storeEnhancer to enhance the store and silently substitute the original state with our own:</p><blockquote>A store enhancer is a higher-order function that composes a store creator to return a new, enhanced store creator. This is similar to middleware in that it allows you to alter the store interface in a composable way.</blockquote><p>A store enhancer has the following form:</p><pre>const storeEnhancer = next =&gt; (reducer, preloadedState, enhancer) =&gt; store</pre><p>The enhancer accepts a single argument — the original createStore, thus may be compose&#39;d. To replace the original state, we’ll enhance use the following enhancer enhanceStore:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a03fb83b0b88ac48b325e15d34f5309d/href">https://medium.com/media/a03fb83b0b88ac48b325e15d34f5309d/href</a></iframe><p>We save the original method store.getState and replace it with () =&gt; deriveState(_originalState).</p><p>Let’s improve the example above — we’ll use an enhancer that is a composition of:</p><ul><li>applyMiddleware (that is used to <a href="https://github.com/reactjs/redux/blob/master/docs/api/applyMiddleware.md">wrap</a> store’s dispatch method)</li><li>our newly introduced enhancer enhanceStore</li></ul><p>We will use compose method supplied by <a href="https://github.com/zalmoxisus/redux-devtools-extension">redux-devtools-extension</a>, if present:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/4a59e655472172ed40225e1296982dad/href">https://medium.com/media/4a59e655472172ed40225e1296982dad/href</a></iframe><p>The enhancer enhanceStore was moved into a separate file:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/89fac6f07296310838ab536e81296e4c/href">https://medium.com/media/89fac6f07296310838ab536e81296e4c/href</a></iframe><p>The interesting part is deriveState — that is the method that accepts the original, non-modified state and adds new deriver fields. The fields are only visible to components that use getState:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/bcc2c6555724266db6c0ff39effc048c/href">https://medium.com/media/bcc2c6555724266db6c0ff39effc048c/href</a></iframe><p>You can notice that the methods booksSummary and userSummary are extracted from the original components Books and Users accordingly, I skipped the rest of mapStateToProps methods from BookDetails and UserDetails to keep the example concise.</p><p>The implementation of deriveState may be extended in many ways to add new, derived state fields that may be used by components (or reused by other derived methods).</p><p>We’d be careful, though, and remember to<a href="https://github.com/reactjs/redux/blob/master/docs/api/createStore.md"> not mutate the state</a>!</p><p><em>Check out this branch to examine the application after the changes </em><a href="https://github.com/agoldis/decouple-redux-state/tree/02-enhance-store"><em>https://github.com/agoldis/decouple-redux-state/tree/02-enhance-store</em></a></p><p>Experienced reader may say that having additional functionality (method members or getter) might violate the <a href="https://redux.js.org/faq/organizing-state#organizing-state-non-serializable">recommendation</a> of having a serializable state.</p><p>“Serializable” means that the we can easily:</p><blockquote><em>Dan Abramov’s </em><a href="https://github.com/reactjs/redux/issues/1407"><em>quote</em></a><em>: </em>serialize, record and replay, hydrate and dehydrate</blockquote><p>Although our enhancer only produces new state when getState method is invoked, and that is not usually an efficient way of serializing the state (it’s better to have it done via another enhancer), we can hide the new computed properties from enumeration, by doing that we prevent the properties from being serialized and comply with the recommendation by setting enumerable: false.</p><p>For demonstration, I have connected redux devtool and implemented “remove book” action — we can time-travel and jump from state to state:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AwrPzOWjjPn4SNGIlUQxnQ.gif" /><figcaption>Time traveling with derived state</figcaption></figure><p>Unfortunately, non-enumerable properties have some associated inconveniences, for example, they are not extracted when spread operator is applied:</p><blockquote>The <a href="https://github.com/tc39/proposal-object-rest-spread">Rest/Spread Properties for ECMAScript</a> proposal (stage 4) adds spread properties to <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer">object literals</a>. It copies own <strong>enumerable</strong> properties from a provided object onto a new object.</blockquote><p>The enhanced store with the derived state allows us to extract mapStateToProps complexity from components — that keeps components simple, allows easy testing of both the components and the methods used to compute the derived state. Moreover, we can modify the original state but keep the changes hidden from components. Let’s try to see how we easily modify the state without additional refactoring.</p><p><strong>Move </strong><strong>users, </strong><strong>books and </strong><strong>tasks to a different branch</strong></p><p>We have decided to move all business-related logic to app branch. No problem! We just define new properties that get the data from new location — state.users becomes state.app.users, and state.tasks becomes state.app.tasks. <em>No changes are required — the components are not aware of state structure modification.</em></p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/478792fe04405a1e530d71d5eb6f0b91/href">https://medium.com/media/478792fe04405a1e530d71d5eb6f0b91/href</a></iframe><p>At the listing above we create getters for the original state properties books, comments and users. Although they were moved within app branch of state:</p><pre>const initialState = {<br>  app: {<br>    comments: { /* ... */ },<br>    users: { /* ... */ },<br>    books: { /* ... */ }<br>  }<br>}</pre><p>none of the components or other methods that computed derived state require refactoring.</p><p><em>Check out this branch to examine the application after the changes </em><a href="https://github.com/agoldis/decouple-redux-state/tree/03-use-app-branch"><em>https://github.com/agoldis/decouple-redux-state/tree/03-use-app-branch</em></a></p><p><strong>Using selectors</strong></p><p>Now let’s try to use <a href="https://github.com/reactjs/reselect">reselect</a> to memoize the “derived” data and prevent expensive recalculations. The point is that modification and/or addition of new tools that help us to manage the state and optimize performance are invisible to the components.</p><p>We start by creating 2 simple selectors: usersSummary and booksSummary, they will be used to prevent recalculation of the derived state when the original state fields that are required for the calculation are not changed.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/31c71a8009079ff930944a457df20106/href">https://medium.com/media/31c71a8009079ff930944a457df20106/href</a></iframe><p>Did we need to touch our components? No! We have added a new state management tool, but components are not aware of its usage — they do not import any of selectors and not aware of their existence!</p><p><em>Check out this branch to examine the application after the changes </em><a href="https://github.com/agoldis/decouple-redux-state/tree/04-use-selectors"><em>https://github.com/agoldis/decouple-redux-state/tree/04-use-selectors</em></a></p><p>The code presented in examples for creating the the derived state might be reorganized and improved, of course, for example, alternative approach could be to return a completely new object every time deriveState is called — that will encapsulate the state completely! Take a look at this example:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/86a95d7bd394db6582e79ebb701161df/href">https://medium.com/media/86a95d7bd394db6582e79ebb701161df/href</a></iframe><p>For clarity, the selectors were moved to a distinct file selectors.js and imported.</p><p><em>Check out this branch to examine the application after the changes </em><a href="https://github.com/agoldis/decouple-redux-state/tree/05-state-object"><em>https://github.com/agoldis/decouple-redux-state/tree/05-state-object</em></a></p><h3>Summary</h3><p>By using this simple technique we achieve a great degree of decoupling of the state (and data management logic) from components. The benefits are:</p><ul><li>easy refactoring</li><li>simple, testable components</li><li>testable data layer logic</li><li>slim “minimal” state</li></ul><p>You can find the source code with fully-functional code of the application I have used while writing this post at <a href="https://github.com/agoldis/decouple-redux-state">https://github.com/agoldis/decouple-redux-state</a>. The branches are used to track the changes:</p><ul><li><a href="https://github.com/agoldis/decouple-redux-state/tree/01-initial-project">01-initial-project</a> — the initial project with state not decoupled from the components</li><li><a href="https://github.com/agoldis/decouple-redux-state/tree/02-enhance-store">02-enhance-store</a> — introduction of store enhancer</li><li><a href="https://github.com/agoldis/decouple-redux-state/tree/03-use-app-branch">03-use-app-branch</a> — we are changing the structure of our state by moving all entities to app branch</li><li><a href="https://github.com/agoldis/decouple-redux-state/tree/04-use-selectors">04-use-selectors</a> — we are using reselect to compute the derived state effectively</li><li><a href="https://github.com/agoldis/decouple-redux-state/tree/05-state-object">05-state-object</a> — demonstration of an alternative approach of organizing deriveState method and encapsulating the state</li></ul><h3>Read more</h3><p>Want to have even more decoupling of your app? Check out those great articles:</p><ul><li><a href="https://hackernoon.com/selectors-in-redux-are-a-must-d6b0637c79b7">Selectors in Redux are a MUST</a> by <a href="https://medium.com/u/8ad5547841c9">Riccardo Odone</a></li><li><a href="https://medium.com/javascript-scene/10-tips-for-better-redux-architecture-69250425af44">10 Tips for Better Redux Architecture</a> by <a href="https://medium.com/u/c359511de780">Eric Elliott</a></li><li><a href="https://techblog.appnexus.com/five-tips-for-working-with-redux-in-large-applications-89452af4fdcb">Five Tips for Working with Redux in Large Applications</a> by <a href="https://medium.com/u/f77f4074e4d6">AppNexus Engineering</a></li><li><a href="http://randycoulman.com/blog/2016/09/13/encapsulating-the-redux-state-tree/">Encapsulating Redux Tree</a> by <a href="https://twitter.com/randycoulman">Randy Coulman</a> (<a href="https://twitter.com/randycoulman">@randycoulman</a>)</li><li><a href="https://blog.javascripting.com/2016/02/02/encapsulation-in-redux/">Encapsulation in Redux: the Right Way to Write Reusable Components</a> by <a href="https://medium.com/u/bd61bb63327a">Tomáš Weiss</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=875c8367350f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to document source code responsibly]]></title>
            <link>https://agoldis.medium.com/how-to-document-source-code-responsibly-2b2f303aa525?source=rss-1bb5b7a41f59------2</link>
            <guid isPermaLink="false">https://medium.com/p/2b2f303aa525</guid>
            <category><![CDATA[opinion]]></category>
            <category><![CDATA[best-practices]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[coding-standards]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Andrew Goldis]]></dc:creator>
            <pubDate>Sat, 31 Mar 2018 05:56:45 GMT</pubDate>
            <atom:updated>2021-03-18T18:43:22.509Z</atom:updated>
            <cc:license>http://creativecommons.org/licenses/by/4.0/</cc:license>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*r3-0BS3yN7-_7j2fMq4Sww.jpeg" /></figure><p>[Edit March 2021]: Hey! It’s 2021, and I discovered an awesome tool that lets you <strong>efficiently communicate decisions / context about your code without polluting it</strong>. Check out <a href="https://www.usecodex.com/">https://www.usecodex.com/</a>.</p><p>The story begins with me, frustrated after a code review comment left by my teammate:</p><blockquote>What this class does? Please document its purpose and how is it used within &lt;whatever&gt; process?</blockquote><p>This comment triggered a chain of long replies, involving attaching <a href="https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/">links</a>, citing widely accepted best practices, mentioning the company’s leadership principles, and the legendary <a href="https://amzn.to/2ZXUzou">“Clean Code” by Robert C. Martin</a>. It turned intense and philosophical.</p><p>I have recently switched from a sweet <a href="https://rollout.io/">start-up</a> to an enterprise full-blown corporate. While still being in observation mode, I have found it funny to actually see most of the <a href="https://www.youtube.com/watch?v=ZsHMHukIlJY">Seven inefficient coding habits</a> by <a href="https://medium.com/u/d9a09a07fe23">Kevlin Henney</a> (comments mentioned <a href="https://youtu.be/ZsHMHukIlJY?t=6m35s">explicitly</a> haha).</p><p>So I have decided to use the power of my frustration to express my point of view here 😃</p><h3>Basics</h3><p>The commenting standards are given to an <a href="https://stackoverflow.com/questions/779025/are-there-standard-formats-for-comments-within-code">interpretation</a> (like many software related matters). Let’s agree (well, I suggest you to agree) to have an invariant basis for the reasoning about the topic.</p><ol><li>Code should be written for humans</li><li>Commenting is an additional tool that a developer can choose to use or not</li><li>Comments <strong>are</strong> part of code</li></ol><p>I believe most people would immediately agree with the first item, while others need deeper dive.</p><h3>Commenting is just another development tool</h3><p>For the second argument, consider this naive example I made up:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/c6d36b5c0a33c7515f24bc435a97b4b8/href">https://medium.com/media/c6d36b5c0a33c7515f24bc435a97b4b8/href</a></iframe><p>It is not a good code, you’d invest few seconds to try and understand what it does.</p><p>Now, we can make it easier for the reader by applying tools like:</p><ol><li>Better naming</li><li>Structuring + naming better</li><li>Commenting</li></ol><p>It’s obvious that commenting is least preferred option. (I would like to mention again, that we are considering the code in terms of being clear). You read the comment and get better idea what’s going on in the code.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/46d3c93ffcc69148a886680590e4fb46/href">https://medium.com/media/46d3c93ffcc69148a886680590e4fb46/href</a></iframe><p>It does the job, may be not good, but now it’s definitely easier to understand. Let’s try and apply another tool — renaming things</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/6ca1bf0c850e9b0d6404d99b190bafbf/href">https://medium.com/media/6ca1bf0c850e9b0d6404d99b190bafbf/href</a></iframe><p>By using proper naming, we can better understand now what the code does.</p><p>And, finally, lets restructure <strong>and</strong> rename:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/42e7f4c185a53849c64d2c2698a3292d/href">https://medium.com/media/42e7f4c185a53849c64d2c2698a3292d/href</a></iframe><p>We see that by applying different tools we provide more clarity, with different degree of success.</p><p>The point is that commenting is indeed only <strong>one</strong> of the tools available for making code more understandable. Sometime it is more successful, sometimes it is not.</p><h3>When you’d prefer to use comments rather than other tool?</h3><p>Comments shine mostly when:</p><ul><li>the reader needs context, that is not possible to express using the existing entities</li><li>the code has to make special assumptions about its environment, if that’s the case — the “special” part of environment should be normalized and the comment removed</li><li><em>“discusses difficult or subtle algorithms and data structures” </em>(<a href="https://pdfs.semanticscholar.org/ba06/f1ecc9014bb832d94eed1ceeeccedf65c6a9.pdf">source</a>)</li><li>other tools cannot be applied (due to limitations of size / time), if that’s the case — comments are obviously temporary</li><li>heavy performance optimization that involve ugliness, well ok</li></ul><h3>Comments are part of source code, and should be treated alike</h3><p>A comment is bound tightly to code it relates to. When code changes, the comment needs to be changed or removed as well. Imagine how confusing would be having a hanging comment that is not related to code!</p><p>While technically it is not code (they are not important for a machine), we agree that the main purpose of a code is to be clear to a human, so we’d treat the comments the same way as, for exampling, naming variables. (And that can also be challenging).</p><h3>The cost of commenting</h3><p>Having agreed on the three basic arguments, let’s consider what is the cost of using comments:</p><ul><li>Comments need maintenance, when refactoring code you have to refactor comments as well</li><li>Good comments are hard to write, good comments should be precise and relevant. Precision requires stability and well-defined requirements / environment that doesn’t change. Lack of changes is a luxury in modern software projects.</li><li>Temptation / culture that promotes using comments prevents developers from writing cleaner, explanatory code.</li><li>Comments hide design issues — the design of a system cannot be expressed effectively with the entities and abstractions that are clear and understandable</li></ul><p>While there is place to have comments here and there to mitigate temporary issues, most commonly commenting is evidence of inability to use other tools (renaming, decoupling, incapsulate) to express intentions of the code written.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/455/1*Pyxsc7Uixbitv5myywaA_Q.jpeg" /></figure><h3>Documentation</h3><p>There’re 2 main consumers for a written code: maintainers and external users.</p><p>Maintainers are mainly concerned with the next questions:</p><ul><li>What the code does</li><li>How the code does it</li></ul><p>External users are interested to know</p><ul><li>How to use the code</li></ul><p><strong>Documentation For External Users</strong></p><p>Traditionally, <a href="https://en.wikipedia.org/wiki/Self-documenting_code">in-code documentation</a> describes <strong>how</strong> to use it. That’s why it is common to document the API provided by a module / package. What makes having documentation in code so convenient is:</p><ul><li>Proximity to the code, i.e. portability</li><li>Ability of tools / IDE to populate some part of documentation automatically</li><li>IDEs ability to parse documentation and show inline hints</li></ul><p>Now, when working on a project consider whether you have any external user? Users that would use your code and need to understand <strong>how</strong> to use it properly.</p><p>So go ahead and write a good documentation, describe the arguments and their type and assumptions; enjoy the automated tools that easily can create nice HTML and PDF.</p><p>Pay attention, though, that often the purpose of adding a formatted comment is not to explain how to use the code, but to include the method in listing of exposed API, i.e. the code is self explanatory and the documentation is only added for integrity.</p><p>Consider this example:</p><pre>CurrencyConverter.<em>convertUsdToEur</em>(15.0);</pre><p>Your IDE will hint you what kind type of arguments is required. It is very clear what this function does because of the naming.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Is6TjV78d36FC7-BY0tEYA.png" /><figcaption>Adding documentation for convertUsdToEur is redundant, in terms of clarity</figcaption></figure><p>You can end up writing documentation, that doesn’t really help understand anything about the code to an external user.</p><pre>public class CurrencyConverter {<br>  <em>/**<br>   * Convert USD to EUR.<br>   * </em><strong><em>@param </em></strong><em>usdAmount amount in USD<br>   * </em><strong><em>@return </em></strong><em>amount in EUR<br>   */<br>  </em>public static Double convertUsdToEur(final Double usdAmount) {<br>    return usdAmount * RATE;<br>  }<br>}</pre><p>May be you’ll want to have it because the documentation is dumped and nicely displayed on a web page / PDF document and if you won’t add the formatted comment, the function will just “disappear” from listing, but its added value in explaining the code is zero.</p><p><strong>Documentation For Maintainers</strong></p><p>Okay, we have a project and there’s a team of developers that work on it.</p><p>You want new / other developers to effectively engage and start development — they need to understand the overall design of the system, the terms and abstractions used, they need to understand <strong>what</strong> the code does and <strong>how</strong>.</p><p>So most chances, your project has:</p><ul><li>Design documentation</li><li>API spec</li><li>Readme</li><li>Contribution guide</li><li>FAQ</li><li>Wiki</li></ul><p>You will want to keep all of these up-to-date — <strong>this</strong> is your project’s documentation.</p><p><em>Not the code.</em></p><p>The information you would want to keep documented inline in code, but not in one of the mentioned items is very limited. Otherwise it will be duplication of information, which is, by obvious reasons is bad.</p><p>You may want to keep the relevant information <strong>close </strong>to the source code for the sake of convenience, but keep in mind that keeping it up-to-date will require and effort. Moreover, having non-updated documentation might be harmful.</p><p>You should document responsibly.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QQUhuRgF0N1A-ZhMWKFESA.jpeg" /><figcaption>This image should simulate your sense of responsibility</figcaption></figure><h3><strong>Summary</strong></h3><p>This kind of extreme commenting and documenting coding standard, and it can be summarized as:</p><blockquote>In long term, good code should have nothing but code and external API documentation.</blockquote><p>No over-documenting; the code should be self-explanatory. The project should have a good documentation and guides, but it should be <strong>minimal</strong> in the source code.</p><p>Of course, the reality is hard. And no idealistic approach can really be achieved in practice. Sometimes extreme opinions are <a href="https://www.youtube.com/watch?v=_v-hzc6blGI">intentionally manipulative</a>.</p><p>I hope that post will help to convince other developers to eliminate the ineffectiveness of over-documenting source code and would allow them to focus on coding aspects that really matter.</p><p>I couldn’t find any research that measures time waste caused by teams that practice over-documenting, but from personal experience — it is significant and, for me personally, frustrating.</p><p>P.S.</p><p>A week after writing this post I have bumped into this funny tweet by <a href="https://twitter.com/codinghorror">@codinghorror</a>. It perfectly illustrates the idea 😂</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/952/1*Uo5ZBB3raGaG2wwa2tQoBA.png" /><figcaption><a href="https://twitter.com/codinghorror/status/983148100301742080">https://twitter.com/codinghorror/status/983148100301742080</a></figcaption></figure><h3>References</h3><p>An excellent <a href="https://medium.freecodecamp.org/code-comments-the-good-the-bad-and-the-ugly-be9cc65fbf83">Putting comments in code: the good, the bad, and the ugly</a> by <a href="https://medium.com/u/7f9c91ba25fb">Bill Sourour</a></p><p><a href="https://www.youtube.com/watch?v=ZsHMHukIlJY">ITT 2016 Seven Ineffective Coding Habits of Many Programmers</a> by <a href="https://medium.com/u/d9a09a07fe23">Kevlin Henney</a></p><p><a href="https://pdfs.semanticscholar.org/ba06/f1ecc9014bb832d94eed1ceeeccedf65c6a9.pdf">A Survey of Improving Computer Program Readability to Aid Modification</a></p><p><a href="https://www.quora.com/What-is-the-difference-between-documentation-and-commenting-while-programming">What is the difference between documentation and commenting</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2b2f303aa525" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Nested BackboneJS Models]]></title>
            <link>https://agoldis.medium.com/nested-backnonejs-models-8adcfac7bdfb?source=rss-1bb5b7a41f59------2</link>
            <guid isPermaLink="false">https://medium.com/p/8adcfac7bdfb</guid>
            <category><![CDATA[backbonejs]]></category>
            <category><![CDATA[marionettejs]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[model]]></category>
            <dc:creator><![CDATA[Andrew Goldis]]></dc:creator>
            <pubDate>Thu, 29 Mar 2018 04:48:20 GMT</pubDate>
            <atom:updated>2018-04-01T04:32:39.634Z</atom:updated>
            <content:encoded><![CDATA[<p>This is a copy of the post I have written while working for <a href="https://rollout.io/">Rollout.io</a> — that’s a really good Israeli start-up that provides nifty solutions for managing <a href="https://martinfowler.com/bliki/FeatureToggle.html">feature flags</a>, using the most advanced industry practices. You can find the original article following this <a href="https://rollout.io/blog/nested-backbonejs-models/">link</a>, it is completely the same though.</p><h3>Nested BackboneJS Models</h3><p>My relationship with Backbone.js is complicated. We have spent a dozen of hours together, full of entertaining and deep conversations (into late night hours). I was really impressed, excited by its simple and gentle perception of the world, its powerful abilities and benefits for one who decides to stick with it. I’ve seen colorful future, the future where we together, hand by hand, build beautiful, simple and reusable UI components, raise them in peace and happiness. In my dreams the components respect each other and cooperate, being attentive to other components’ events, listening carefully and responding appropriately and respectfully. That was a dream.</p><p>After a while I’ve started to pay attention that not everything is perfect. Backbone was demanding, gelous for details. It required all my attention while we were rendering views together, we had fun preventing memory leaks, but it was difficult as well, as both of us were blaming each other for creating them. I was told once that I do not really understand it. Slowly, my excitement started to decline, I’ve discovered myself starting to look at other front-end frameworks, they were sexier, younger, more attractive.</p><p>However, after many hours and lines of code that we’ve spent together, it was hard to break up just like that. I had obligations as well — I’ve promised to take care of the views and models we’ve created together, respect all the effort and investment we’ve made so far. We’ve agreed to make some changes, used Marionette to make Backbone more attractive, attached some plugins for cosmetics and performance.</p><p>Things look much better since then. We manage to be together, despite all the difficulties, not always agreeing and understanding each other, but we do have fun; the secret is to find a common language and be respectful to each other’s demands.</p><h3>Nested Models</h3><p>Here at Rollout.io we had a desprate need for a nested model — the data structures we work with have a strong “nested” orientation. There are many reasons for that, here are some of them that I think are reasonable:</p><ul><li>The document storage concept of MongoDB implies using a similar concept at front-end side — i.e. you get a single document that might have a nested subdocuments</li><li>Single network request is required to get all your data with a nested document-like structure, pulling subdocuments from an API would require multiple network requests, you’d also configure and implement API endpoints for each such request</li><li>Breaking a document to sub-documents (and assembling them back) is a tedious and time-consuming</li><li>Conceptual simplicity of nested model is obvious — while technically it may be more difficult to implement and use a nested model, it might be easier to understand the design of an application data layer while working with intuitive terms that are appropriately reflected as nested models</li></ul><p>There’s quite a lot of discussion about the concept of nested, or deep model, including the comment of BackboneJS Jeremy Ashkenas on GitHub and BackboneJS official FAQ <a href="http://backbonejs.org/#FAQ-nested">section</a>.</p><p>The arguments of not using nested model sound reasonable and it is up to you to decide whether to use the concept or stick with the original interpretation of flat, simple models as proposed by respective developers.</p><p>To showcase the problem, let’s see a small example that highlights the issues I’ve mentioned.</p><h3>Feel the pain</h3><p>Imagine you have a person schema in your MongoDB storage. Each person may have 0 or more phone numbers associated. Each phone number has a label, e.g. home, work, mobile and the actual number. A person document would be represented as:</p><pre>var data = {<br>   name: &#39;Bob&#39;,<br>   lastName: &#39;Flop&#39;,<br>   email: &#39;bob.flop@email.com&#39;,<br>   phones: [<br>       {<br>           label: &#39;Home&#39;,<br>           number: 101<br>       },<br>       {<br>           label: &#39;Work&#39;,<br>           number: 102<br>       }<br>   ]<br>};</pre><p>The document presentation as a Backbone model would have the following keys of its attributes:</p><pre>var personModel = new Backbone.Model(data);<br>_.keys(personModel.attributes)<br>&gt; [&quot;name&quot;, &quot;lastname&quot;, &quot;phones&quot;]</pre><p>You cannot get access to phone object details directly using `Backbone.Model.get`:</p><pre>personModel.get(&#39;phones[0].label&#39;)<br>&gt; undefined</pre><p>In order to access the sub-documents of phone , it’s required to iterate over the phones array:</p><pre>var phones = personModel.get(&#39;phones&#39;);<br>phones.map(function(phone) {<br>  // do stuff with phone<br>});</pre><p>The instance of phone object is not a Backbone model — you cannot apply the common Backbone patterns (like `get`, `set`, `validation` , there’s no events propagation). In order to use the object, we need to “backbonify” it, creating a new generic Model and wrap phone object in it:</p><pre>var phones = personModel.get(&#39;phones&#39;);<br>var phoneModels = phones.map(function(phone) {<br>var phoneModel = new Backbone.Model(phone);<br>  return phoneModel;<br>});<br>console.log(phoneModels);<br>&gt; [Backbone.Model, Backbone.Model]</pre><p>However, the newly created phone models are not connected in any matter to the original person model. That means that:</p><ul><li>No events propagation across the model, changing an attribute on phone model doesn’t trigger change event on person</li></ul><pre>personModel.on(&#39;change&#39;, function (e) {<br>  console.log(&#39;person has changed&#39;);<br>});<br>phoneModels[0].set(&#39;number&#39;,999);<br>// no change in person</pre><ul><li>No validation happens for person model when phone model is changed, i.e. you need to implement distinct validation logic for phone and for person model in order to get the validation process happen as soon as some property of phone model changes.</li><li>Eventually we’d need to send the modified person model to backend, that will require to handle all the changes in phones sub-models and to send a unified single model to our backend servers.</li></ul><h3>The shine of nested model</h3><p>Now, after we’ve tasted a bit of disadvantages when dealing with non-primitive models, imagine how wonderful would it be, if we could just easily access all nested attributes of the main person model and use native Backbone mechanics like events handling and validation.</p><p>That’s what nested model allow us to do. The main advantage is that all nested attributes are accessible directly, using native JS syntax.</p><p>There’re different implementations of nested models available, here are some of them:</p><ul><li><a href="https://github.com/powmedia/backbone-deep-model">https://github.com/powmedia/backbone-deep-model</a> (<a href="https://twitter.com/charliedavison">@charliedavison</a>)</li><li><a href="https://github.com/blittle/backbone-nested-models">https://github.com/blittle/backbone-nested-models</a> (<a href="https://twitter.com/little_bret">@little_bret</a>)</li></ul><p>There’re also several projects that implement the concept of “complex” model by applying a “relational” approach, i.e. predefining relations between different models and handling inter-relationships accordingly:</p><ul><li><a href="http://backbonerelational.org/">http://backbonerelational.org/</a></li><li><a href="https://github.com/dhruvaray/backbone-associations">https://github.com/dhruvaray/backbone-associations</a> <a href="https://twitter.com/dhruvaray">@dhruvaray</a></li></ul><p>We’ll skip the relational (or related) models and will focus on nested models implementation — the usage is very simple, extending your model from a generic Nested Model would give you effortless access to all its attributes, triggering events properly and handling validation process fluently:</p><ul><li>Get access to nested data with no effort, using JS syntax:</li></ul><pre>var nestedPersonModel = new Backbone.NestedModel(data)<br>nestedPersonModel.get(&#39;phones[0].label&#39;)<br>&gt; &quot;Work&quot;</pre><ul><li>Events are handled properly:</li></ul><pre>nestedPersonModel.on(&#39;change:phones&#39;,<br>  function () {<br>    console.log (&quot;Person has changed&quot;);<br>});<br>nestedPersonModel.set(&#39;phones[0].label&#39;, &#39;Office&#39;);<br>&gt; Person has changed</pre><ul><li>Validation works as expected:</li></ul><pre>// define validation - disallow duplicated phone labels<br>var NestedPersonClass = Backbone.NestedModel.extend({<br>  validate: function (attrs, options) {<br>    var uniqueLabels = _.uniq(_.pluck(attrs.phones, &#39;label&#39;));<br>    if (uniqueLabels.length !== attrs.phones.length) {<br>      return &#39;Duplicated phone labels are not allowed&#39;;<br>    }  <br>  }<br>});<br>var nestedPerson = new NestedPersonClass(data);<br>nestedPerson.set(&#39;phones[0].label&#39;, &#39;Work&#39;, {validate: true} )<br>&gt; false<br><br>console.log(nestedPerson.validationError);<br>&gt; &quot;Duplicated phone labels are not allowed&quot;</pre><p>As we’ve seen, most of the problems we’ve been suffered when using the original, flat models, are solved. Now we can work with the unified model that has identical presentation in storage and front-end.</p><h3>Messing with nested models</h3><p>Despite all the advantages of nested models, they are still not perfect. The problem is that by using a nested data structures together with Backbone (and with Marionette extensions like CollectionView, Layout etc.), we are breaking the workflow and simplicity of Backbone views.</p><p>The Views (and Collection / Layout views) are designed to work with simple, flat models. Having a unified but complicated nested model and passing it to views requires specifying what part of the ‘big’ model is accessible for the specific view.</p><p>We’ve been utilizing this technique, passing a nested model between Layout and its sub-views, after reaching a certain level of complexity, we’ve started to get messed with defining paths for ItemViews that get the whole nested model to properly define data chunk that the view should have access to:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/847/1*9xC9hWDYt7MeECKqm9Xwiw.png" /></figure><p>The complexity of serving the correct model for ItemViews is in the scope of the Layout View, and often it is not trivial to change the current sub-item (technically, changing the index `i` or `j`). The implementation of the ItemViews and Layout were not intuitive and hard-to-follow, as every access change in the nested model required recalculating the paths (index values) and re-rendering the dependent part of associated Views.</p><p>Moreover, the bigger pain we’ve felt was the lack of ability to create a native collections that may be used by CollectionViews properly. As a workaround we’ve started to create a ‘dummy’ collections that are ‘bound’ to the original nested model and serve as a proxy for convenient using in collection-based views.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*E0D7rezuJj2K0TG8pJEPIw.png" /></figure><p>The workaround we’ve used allowed us to overcome the lack of ability to natively create collections from embedded nested elements. However, the solution we’ve used was not generic enough and was tailored only for specific needs; for example, the binding between proxy collection and the nested collection is one-directional, i.e. changes in the nested model are not being reflected in the proxy collection elements (we had no need to propagate changes in other direction).</p><p>The simplified version of the ‘proxy’ collection looks like:</p><pre>var SubCollection = Backbone.Collection.extend({<br>  // sync data to the original nested model when needed<br>  flushData: function(model, path) {<br>    var arrayPlaceholder = [];<br>    this.forEach(function(model) {<br>      return arrayPlaceholder.push(model.toJSON());<br>    });<br>    model.set(path, arrayPlaceholder);<br>    return model.save();<br>  };<br><br>  // bind the collection to the specific path of a nested model<br>  bindToModel: function(model, path) {<br>    var dataArray, item, i, len;<br>    dataArray = model.get(path);<br>    this.on(&#39;change&#39;, function() {<br>      this.flushData(model, path);<br>    });<br><br>    this.on(&#39;remove&#39;, function() {<br>      this.flushData(model, path);<br>    });<br><br>    for (i = 0, len = dataArray.length; i &lt; len; i++) {<br>      item = dataArray[i];<br>      // create sub-models from the array elements of the nested model<br>      this.add(item);<br>    }<br>  };<br>});</pre><h3>The sub-models utopia</h3><p>So, what would be the ideal approach for working with complex data models? In order to fluently use all the goodies of Backbone-Marionette ecosystem, that’s designed to work with simple and flat models, without manually breaking the data structure into smaller not-connection chunks, it would be ideal to:</p><ol><li>Be able to create a new sub-model from any path of the ‘big’, nested model. The newly created sub-model should behave like a distinct Backbone model, but is is also has to be tightly bound to its ‘parent’ in terms of data integrity, events propagation, validation etc.</li><li>Be able to create a collection of sub-models from array-like members of a nested model, having all the bindings listed above working correctly.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1008/1*-vA7ireelpbR6kLARkI6Nw.png" /></figure><p>The approach that’s presented in the ‘dummy’ proxy collection is quick and dirty trial to implement this solution with very limited functionality, the generic solution (I wish I had) should have a bidirectional binding and well-defined events propagation logic.</p><p>Having such an powerful feature would significantly enhance developers’ ability to deal with complex data structures, creating sub-models and sub-collection on demand, and using them natively with Backbone/Marionette Views and Layouts.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8adcfac7bdfb" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>