<?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 Grammarly on Medium]]></title>
        <description><![CDATA[Stories by Grammarly on Medium]]></description>
        <link>https://medium.com/@Grammarly?source=rss-d1e3c14169c8------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*msZeb99d8ha_J6tV.jpg</url>
            <title>Stories by Grammarly on Medium</title>
            <link>https://medium.com/@Grammarly?source=rss-d1e3c14169c8------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 02:09:28 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@Grammarly/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[Part 2: How Grammarly tackles hidden complexity in front-end applications]]></title>
            <link>https://medium.com/engineering-at-grammarly/part-2-how-grammarly-tackles-hidden-complexity-in-front-end-applications-12e22ecb5342?source=rss-d1e3c14169c8------2</link>
            <guid isPermaLink="false">https://medium.com/p/12e22ecb5342</guid>
            <category><![CDATA[frontend]]></category>
            <category><![CDATA[engineering]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Grammarly]]></dc:creator>
            <pubDate>Wed, 02 Oct 2019 14:01:01 GMT</pubDate>
            <atom:updated>2020-01-02T04:22:53.381Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Written by </em><a href="https://medium.com/u/c59bcb97bf84"><em>Anton Pets</em></a><em> and </em><a href="https://medium.com/u/2fe52066abf2"><em>Yaroslav Voloshchuk</em></a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Cu4AwTk3rLfH4RTq" /></figure><p><em>Read the original article and more on </em><a href="https://www.grammarly.com/blog/engineering/"><em>Grammarly’s new engineering blog</em></a><em>!</em></p><p>In <a href="https://medium.com/engineering-at-grammarly/part-1-how-grammarly-tackles-hidden-complexity-in-front-end-applications-1b22b10a24d5">our last post</a>, we examined some of Grammarly engineering’s process-based methods of reducing complexity, derived from research, experience, and classic computer science guidelines. In this post, we’ll look at how we reduce complexity in the code itself, starting with our complexity pyramid, which informs our choices throughout the front-end development process and helps ensure that engineering hours are invested well. We hope to provide you with ideas for designing your code, educating yourself, and leveraging classic ideas of computer science to reduce complexity — from the start of project planning all the way to the final PR merge.</p><p>Complexity can creep in from anywhere: from new challenges or familiar problems. The latter can be especially insidious because we’re likely to be less suspicious of common issues. Consider email validation, a commonly encountered task. Shouldn’t it be a straightforward matter of working out the correct regex, validating it, and calling it done?</p><p>Alas, regex for email validation isn’t simple. And once you finally nail down a long string of regex pattern, you still need to send an email with a validation link that the user has to click. This creates obstacles: An extra step means a drop in conversions. Users sometimes can’t find the emails, or maybe just won’t take that extra step of opening to click.</p><p>We might address this problem by starting to send email addresses to the server — to check the <a href="https://en.wikipedia.org/wiki/MX_record">MX records</a> for the domains — while the user fills out the form. It’s not a bad fix, but it brings the inherent complexity of MX record validation into play.</p><p>Because that’s how complexity grows: By solving one issue you might add several new ones. Figuring out how to avoid doing so is difficult — but we’ve worked through a few processes that can help.</p><h3>The structure of code complexity</h3><p>There are two types of complexity in software: structural and behavioral. Structural complexity represents the built connection between your application’s components. Behavioral complexity comes into play when these components interact: when they start sending messages to one another at runtime. Behavioral complexity is strongly connected to how a user interacts with the system, whereas structural complexity is more about how engineers build the system. In this article, we will mostly focus on structural complexity.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*krQbM4bYuYJVipZB" /><figcaption>The complexity pyramid</figcaption></figure><p>In code, complexity occurs at increasing levels of abstraction. The complexity pyramid shown above is one way to think about how an engineer will encounter them. Let’s climb the pyramid to see what might help us at each level. We’ll need to reconsider basic code blocks that we might take for granted as having mastered: statements, functions and methods, and modules and classes. We’ll even need to reconsider how we think about applications themselves.</p><p>But first, we need to discuss some of the major tools in our arsenal for minimizing complexity up the pyramid.</p><h3>Allies against complexity</h3><h4>Functional programming: Almost a silver bullet</h4><p>In the previous post, we agreed that there is <a href="http://www.cs.nott.ac.uk/~pszcah/G51ISS/Documents/NoSilverBullet.html">no silver bullet </a>to fight software complexity. But a central part of overcoming complexity is ensuring that your code works predictably. One way we do this at Grammarly is by using statically typed functional programming.</p><p>Consider this level of excitement about FP:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*rEQXp66qf1ShNSKg" /></figure><p>We introduced static typing at Grammarly, which had helped us vastly improve our code quality but left us still struggling with unpredictability and complexity. That’s when functional programming entered our toolkit.</p><p>One particularly challenging task we encountered was synchronizing a user’s text between front-end and back-end. If a user clicks on the Correct Mistake button, for example, the error correction event should first go to the server. Only then should we correct the text in the browser and send the updated document to the server. If done in the wrong order, our back-end tries to handle the correction event on the already corrected text — and consequently produces an incorrect state. The two events — correcting a mistake and updating text — are examples of <a href="https://en.wikipedia.org/wiki/Side_effect_(computer_science)">side effects</a>. Coordinating multiple asynchronous side effects in a complex UI system is difficult and can be a limitless source of bugs.</p><p>We were able to address some of these side-effect issues once we began using functional programming, which was introduced to our team by colleagues that had backgrounds in <a href="https://fsharp.org/">F#</a>. The first FP citizen in our repository was <a href="https://gcanti.github.io/fp-ts/modules/Option.ts.html">Option</a> (aka <a href="https://wiki.haskell.org/Maybe">Maybe</a>) type, which is now used all over our codebase. Later, we discovered existing FP libraries that provide nuanced ready-to-use tools for controlling side effects elegantly. Because FP abstractions are universal (they operate like extremely forceful <a href="https://blog.ploeh.dk/2017/10/04/from-design-patterns-to-category-theory/">design patterns</a>), the FP-powered solutions are easier to understand and reuse. We diminished our side-effect problems by using this functional approach, and now we always prefer declarative FP solutions to imperative or class-based code.</p><h4>Types: An underrated (and critical) ally</h4><p>Another major ally to consider in the fight against complexity: the use of types.</p><p>Though we know it can seem to add complexity when you adapt an existing codebase to have types, <a href="https://noti.st/oopets/UBVXZ9/how-fp-made-grammarly-codebase-error-free-predictable#sW1N0lq">our own experience</a> is that incorporating types merely surfaces unavoidable complexity already in the code.</p><p>So if your code is clumsy: Yes, adding types will result in clumsy types. Though this can itself be a step toward conquering complexity. Having a combination of different function calls with complex parameters can make it hard to understand the underlying logic. But when types are used, it becomes obvious what are the inputs and outputs of functions — and, consequently, it becomes easier to understand the behavior.</p><p>Without types, there is no verification before code execution (except code linters, which are more of a crutch used in the absence of types). There are no very compelling reasons not to use types, as static typing doesn’t add overhead at runtime in almost any available languages compiled in JavaScript. Some examples: <a href="https://www.typescriptlang.org/">TypeScript</a>, <a href="https://elm-lang.org/">Elm</a>, <a href="http://www.purescript.org/">PureScript</a>, <a href="http://reasonml.github.io/">Reason</a>, and <a href="http://ocaml.org/">OCaml</a>.</p><p>Grammarly’s Editor was originally written in Javascript because there were no popular statically typed languages that could compile into JavaScript at the time. Later, as the complexity of the app grew, the Editor became harder to support, and it was not easy to improve a big codebase without compile-time verification. So we started to research options for compiled-to-JavaScript languages that could meet our needs. We analyzed many options, including TypeScript, PureScript, and <a href="https://www.scala-js.org/">Scala.js</a>. In the end, we chose TypeScript because it has a robust ecosystem and community of support. Even more, TypeScript is a superset of JavaScript, and so it was easy to adopt.</p><p>We completely rewrote our Editor in TypeScript so we could make a fair comparison with JavaScript. Long before the last commit was made, we knew we preferred TypeScript, so we used it to develop Denali, the latest generation of the Grammarly Editor.</p><p>How does this language switch relate to functional programming and our journey to limit complexity? JavaScript has all the necessary attributes to be an effective functional language: first-class functions, lambda functions, and closures. But functions in JavaScript are not pure, and data is not immutable. Furthermore, the lack of static typing makes it harder to compose neat functions because composition requires some contracts to be respected, and there are some other <a href="https://dev.to/wolksoftware/why-typescript-is-a-better-option-than-javascript-when-it-comes-to-functional-programming-3mp0">advantages of types in FP</a>. For this reason, TypeScript is a better option for FP — especially now that we have such FP libraries as <a href="https://github.com/gcanti/fp-ts">FP-TS</a> and <a href="https://github.com/funfix/funfix">Funfix</a> — and thereby a better ally for limiting complexity.</p><p>So even though there is no one fix to eliminate complexity entirely, we agree with Mark Seeman’s points in <a href="https://blog.ploeh.dk/2019/07/01/yes-silver-bullet/">“Yes Silver Bullet”</a>: Statically typed functional programming is as close to a silver bullet as we’ve found.</p><h3>Structural Complexity</h3><p>Now that we’ve discussed functional programming and the benefit of using types, we can return to our pyramid fully outfitted for success. Let’s address complexity from the bottom up, starting at the level of statements.</p><h4>Statements: Unchanging variables and handling predictable exceptions</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*G_SJaf6xBWWK8esK" /></figure><p>Some of functional programming’s most helpful characteristics come from some pretty elemental guidelines. To start: When possible, we use <em>readonly </em>variables, which keep the changes created by our functions compact and predictable, and our parameters unchanged.</p><p>We also try to contain unexpected effects by using <em>for/while </em>loops only in performance-sensitive places. <em>For/while </em>loops are powerful tools but are notorious for creating problems (there’s a reason Apple headquarters’ original address was 1 Infinite Loop). We use them judiciously and only when we know they’re the best option.</p><p>Finally, we try to perform idiomatic handling for empty values and errors with <em>Try </em>and<em> Option</em>. <a href="https://gcanti.github.io/fp-ts/modules/Option.ts.html"><em>Option</em></a> is an object type that may or may not have a value; this type is used to prevent undefined and null objects and their resulting errors. <em>Try</em> is an object that can be completed either successfully or unsuccessfully, without the need to catch exceptions in your application. By using these, you can be less defensive in your programming.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*2Dec7hdJPlfrHLi-" /><figcaption><em>Idiomatic handling of empty values and incorrect data</em></figcaption></figure><p>In the code above, we get an <em>Option</em> — that is, an optional parameter — and try to parse it with <em>Try</em>. First, we do it in one way, and if that doesn’t work, we try to recover in another way, which can enable your code to support two different formats of stored app configuration (in the case of json.parse, a JSON string). Then we try to validate it; if the validation worked, we merge it with our basic config and return it. If at some point the values we needed to proceed through the entire function are not there, we return the default value. And as we discussed with <em>readonly</em> variables the original variables supplied as parameters are unchanged and still available to other functions as needed.</p><h4>Functions: Clear, pure, and SOLID</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*1JRRm1pz7nly1LsU" /></figure><p>When possible, we prefer <a href="https://medium.com/javascript-scene/master-the-javascript-interview-what-is-a-pure-function-d1c076bec976">pure functions</a>, and we try to avoid conditional <em>if</em> statements for switching behavior.</p><p>For instance, we have a function that writes logs, and when we run it in the local environment, it writes to the console. Instead of making one function with conditional checks, we make it <a href="https://dev.to/jvanbruegge/what-the-heck-is-polymorphism-nmh">polymorphic</a> with two different implementations. The correct one will be used depending on the parameters supplied. Here’s an example:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*vGvi_p1e2CLzY2zl" /><figcaption><em>We prefer polymorphism over if statements</em></figcaption></figure><p>For polymorphism, it is important to respect two important principles from <a href="https://khalilstemmler.com/articles/solid-principles/solid-typescript/">SOLID</a> — a classic set of computer science principles that we keep in mind throughout our work. First, the single responsibility principle states that each function or method should be responsible for just one thing. This makes our code more deliberate, clear, and predictable. Second, the <a href="https://www.tomdalling.com/blog/software-design/solid-class-design-the-liskov-substitution-principle/">Liskov substitution principle</a> states that we should be able to easily switch from one function implementation to another.</p><p>Another way of ensuring clarity is to avoid class methods that can leave the class in a disassembled state. For example, when we create an alert in the user’s text (an object that stores information about a specific error or an issue, including its position in text and possible ways to fix the error or issue), we must register this alert with the positionManager, which is an entity that controls the absolute position of the alert in text.</p><p>If we haven’t registered the alert, we can’t do anything with it, so if an operation happens without registering the alert, we’ll get an exception. To avoid this, we should design our system so the object is provided what it needs from the start.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*wYig6Q46WmWkbTGS" /><figcaption><em>Don’t break invariants</em></figcaption></figure><p>The composition is critical, and we use it frequently with functions, classes, and objects. When used with functions, it opens up a whole stream of possibilities in the form of <a href="https://scotch.io/tutorials/understanding-memoization-in-javascript">memoization</a>, <a href="https://dev.to/benlesh/a-simple-explanation-of-functional-pipe-in-javascript-2hbj">piping</a>, and other useful perks. We can also use composition to divide function logic from error recovery — e.g., to isolate handling JSON parsing errors from the actual usage of the parsing result. This then empowers us to use and combine different error-handling strategies inside a function without rewriting its logic.</p><p>Finally, it’s essential to write functions with a clear and easy-to-use interface. In the example below, the parse function takes a data parameter, and what it does internally may not be immediately evident in its twenty lines of code (to say nothing of much longer functions). If you specify that the function returns <em>Try</em>, engineers using your function later will be grateful, and future engineers will find it much easier to maintain the codebase.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*CQLhka8LoEQ4GMLK" /><figcaption><em>Make self-explaining signatures</em></figcaption></figure><h4>Modules and classes</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*W6l1o6de9BKmND-C" /></figure><p>Although types bring considerable benefits at each level of the complexity pyramid, their utility becomes most evident at the class and module level. At this level, engineers start to think in terms of software architecture. We think through the design of our modules, how they interact, and their APIs, using types to describe these aspects. Then we implement our architecture, integrating work from other Grammarly engineers that might use different libraries or frameworks. Having clear types in place ensures that we can manage these different sources of complexity for this commit — and future ones too.</p><p><strong>Invariance in types<br></strong>In general, when constructing types, it’s best to ensure that they cannot express an incorrect or somehow contradictory state. Let’s imagine, for instance, that we are implementing an interface for a bulb switcher. We might inadvertently create an unpredictable state, like trying to switch off a bulb that’s not on. The solution would be creating a specialized bulb interface that does not allow such behavior. Consider the code sample below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*tZC8YlyiOQgU31Vx" /><figcaption><em>Use types to prevent incorrect state of an app</em></figcaption></figure><p>In some languages, such a design can be achieved with the help of algebraic data types.</p><p><strong>Algebraic data types<br></strong>This principle dictates that we cannot read data from a state that is incorrect according to the type system. By avoiding contradictory states, we can avoid complexity.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*fhHqEJBXrQeOvAeo" /><figcaption><em>Algebraic data types in action</em></figcaption></figure><p><strong>Correct data structures for better performance<br></strong>Strong types help ensure that you’re using the right data structures and not defaulting to simple arrays and objects, which can be suboptimal. A few examples:</p><ul><li><strong>Set vs. Array: </strong>If you need only unique values, use <em>set</em> instead of <em>array</em>, as it provides a quick uniqueness check.</li><li><strong>Prefix tree vs. Hash table: </strong>This is an important distinction for search functionality. For instance, if you needed to create an English-language dictionary that will be frequently searched but rarely modified, then you might use a prefix tree. Looking up data will be faster, even in a worst-case scenario, compared to an imperfect hash table that contains many key collisions. Moreover, using a hash table for this would require a huge amount of allocated memory, which is especially important to consider for front-end apps.</li></ul><p><strong>Data heading/encapsulation<br></strong>This classic software engineering principle dictates that our variables, functions, and classes should have the smallest possible scope. Avoid exporting or importing unnecessary artifacts. Hide nonessential variables inside closures instead of storing them inside a class. Try not to clutter your namespaces.</p><p><strong>Separation of concerns</strong><br>This principle dictates that responsibilities are distinctly separated. For example, imagine that you need to implement functionality for bank-transaction processing. In addition to the core business logic, this task also requires authorization, logging, tracking, and other functions. You will want to isolate all these concerns into separate modules. Mixing them all into a single function or class risks turning into unsupportable spaghetti code.</p><p><strong>Composition over inheritance<br></strong>Inheritance is one of the ways to implement polymorphism. When we use it for composition, however, we end up with highly coupled, inflexible, and fragile architectures. Composition is usually <a href="https://medium.com/javascript-scene/the-hidden-treasures-of-object-composition-60cd89480381">preferable</a>.</p><h4>Applications and subsystems</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*_YbkO59UdA1dei2R" /></figure><p>Before we move on from discussing the structural complexity of building an app, we wanted to talk about complexity at the level of the application itself. This can sit between the code level — which we just discussed — and the behavioral areas. There are some shared principles that can help a project move cleanly from discussion through to implementation.</p><p>To start, we try not to reinvent the wheel when writing code, because less new code means less maintenance. If we have a need our current code and libraries don’t address, often there’s an existing library that will cover it — and our job, when we’re planning out a project’s architecture and code, is to find it. Design patterns and frameworks are similar. Many common problems are already well solved and don’t require a new or different solution. Sometimes engineers feel ambitious and are drawn to a challenge, but good planning can mean the difference between a successful project and one that requires a difficult retro.</p><p>We also suggest using a trustworthy runtime library — we like <a href="https://github.com/gcanti/fp-ts">FP-TS</a>, <a href="https://ramdajs.com/">Ramda</a>, <a href="https://immutable-js.github.io/immutable-js/">Immutable.js</a>, and <a href="https://github.com/lodash/lodash/wiki/FP-Guide">lodash/fp</a>. We keep our list of tools up to date through ongoing team self-education and sharing resources and papers with one another. We like <a href="https://dev.to/">dev.to</a>, <a href="https://blog.acolyer.org/">The Morning Paper</a>, <a href="https://overreacted.io/">Dan Abramov’s blog</a>, and <a href="https://github.com/xgrommx/awesome-functional-programming">this extensive repo of functional programming resources</a>.</p><h3>Behavioral complexity</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*UZ5xLQpVVvjyIhkS" /></figure><p>Though behavioral complexity is a subject that’s too big for one blog post — much less a section of one — it’s important to examine how it fits into our discussion about structural complexity. If we look back at our complexity pyramid, we’re now going all the way back to the base of product requirements. Behavioral complexity is a concern from that early stage and continues running alongside all the structural concerns we’ve been discussing.</p><p>Behavioral complexity in front-end applications at Grammarly is often caused by the asynchronous nature of human-computer interaction. We have struggled with common front-end challenges like callback hell and orchestrating application actions via event emitters. But one thing has made our life noticeably better: <a href="https://gist.github.com/staltz/868e7e9bc2a7b8c1f754">functional reactive programming</a> (FRP). We found it especially effective to manage application state. We even created our own state management framework, <a href="https://github.com/grammarly/focal">Focal</a>, which leverages our favorite parts of React and RxJS.</p><p>To illustrate how one might deal with this type of complexity, let’s look at an example of functional reactive programming usage. Here we are waiting for the user’s mouse to get into a certain area of Grammarly’s Editor; after that, we will start tracking mouse moves. Our task is to find DOM nodes under the pointer. For performance reasons, we don’t want to immediately notify the system about the mouse leaving the area, so we add a 200-millisecond delay. Finally, we filter duplicates of those states so we don’t overload the system with unnecessary actions.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ApbZbSzHYr3VjE-Tz3OKzw.png" /><figcaption>An example of dealing with behavioral complexity the FRP way</figcaption></figure><p>There are a lot of complicated things going on here — and keep in mind that this code would be much longer if it were written in imperative style. In fact, just to show this complex sample, we had to violate some of the principles discussed above. Namely, the single responsibility principle is not respected, and some functions are not separated into their own modules.</p><p>But perhaps this itself is the best illustration of complexity: Even just demonstrating and explaining how to manage, it can be so complicated you might need to question whether you’re taking the right approach. You might even have to go back to the beginning and make sure you planned things out correctly. (But don’t worry — we won’t do that to you in this post.)</p><h3>Takeaways</h3><p>Complexity in software engineering is — no surprise — a very complex subject. We can never fully eliminate it, but with the use of long-lived principles (such as SOLID) and the use of recent engineering advances (such as recent functional programming libraries like ft-ts), we can reduce it enough to make reliable software that isn’t a burden to maintain. Even just incorporating one or two of the above ideas might make your team’s work measurably easier. With a strongly typed language here and the adoption of <em>readonly</em> variables there, adding a new feature becomes that much less burdensome.</p><p><strong><em>Do you want to take on the complexity of improving the way millions of people communicate? Check out our open roles at </em></strong><a href="https://www.grammarly.com/jobs"><strong><em>grammarly.com/jobs</em></strong></a><strong><em>!</em></strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=12e22ecb5342" width="1" height="1" alt=""><hr><p><a href="https://medium.com/engineering-at-grammarly/part-2-how-grammarly-tackles-hidden-complexity-in-front-end-applications-12e22ecb5342">Part 2: How Grammarly tackles hidden complexity in front-end applications</a> was originally published in <a href="https://medium.com/engineering-at-grammarly">Building Grammarly</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Perfecting smooth rolling updates in Amazon Elastic Container Service]]></title>
            <link>https://medium.com/engineering-at-grammarly/perfecting-smooth-rolling-updates-in-amazon-elastic-container-service-690d1aeb44cc?source=rss-d1e3c14169c8------2</link>
            <guid isPermaLink="false">https://medium.com/p/690d1aeb44cc</guid>
            <category><![CDATA[aws]]></category>
            <category><![CDATA[containers]]></category>
            <category><![CDATA[devops]]></category>
            <category><![CDATA[docker]]></category>
            <category><![CDATA[aws-ecs]]></category>
            <dc:creator><![CDATA[Grammarly]]></dc:creator>
            <pubDate>Mon, 26 Aug 2019 16:01:01 GMT</pubDate>
            <atom:updated>2020-01-02T04:23:09.637Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Written by </em><a href="https://medium.com/u/efb007b13449"><em>Volodymyr Sorokin</em></a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*yrz3wElIvrv9YtTJ" /></figure><p><em>Read the original article and more on </em><a href="https://www.grammarly.com/blog/engineering/"><em>Grammarly’s new engineering blog</em></a><em>!</em></p><p>Grammarly’s writing assistant serves twenty million people every day. Supporting such an involved user base with a smooth rolling update of the application cluster could present a real maintenance challenge. But luckily there are services that facilitate making incremental updates with zero downtime. One option for our engineering team to consider using is Amazon ECS, which can simplify the update process with a procedure called rolling update deployment.</p><p>In this article, we will talk about how we can make rolling updates with Amazon ECS. We will also look more closely at graceful shutdown procedures along with how to deal with long-lived sessions.</p><p>Without further ado, let’s dive into the nitty-gritty.</p><h3>Run and roll</h3><p>Amazon ECS works based on tasks. These can be thought of as single application instances, which may consist of one or more of Docker containers. (It is common to have just one container in a task.) ECS service configuration defines the desired number of task instances, or just tasks, for horizontal scalability.</p><p>To carry out a rolling update deployment in ECS, you follow these two steps:</p><ol><li>Register a new task definition using the AWS ECS register-task-definition command.</li><li>Launch a service update using the AWS ECS update-service command.</li></ol><p>ECS then restarts all tasks, honoring the minimum healthy percent parameter. This ensures a zero-downtime deployment.</p><p>When ECS replaces a task during a <a href="https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-service.html">service update</a>, it executes a Docker stop, which issues a SIGTERM signal to the application process then waits 30 seconds for a container to stop (<a href="https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html">ECS_CONTAINER_STOP_TIMEOUT</a>). If the container is still alive after that, a SIGKILL is issued and the container gets forcibly stopped.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*C8sUVz7VlTVMPOsF" /></figure><p>When a load balancer is attached to the service, there are two further steps. ECS first removes the task from the load balancer. Then, before executing a Docker stop, it waits for the load balancer to drain active connections. This draining delay is called a deregistration delay and can be configured in the <a href="https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-target-groups.html#deregistration-delay">load balancer target group settings</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*iigFzHVR7sbTBp7N" /></figure><h3>Long live the connection</h3><p>This draining approach works great for the majority of cases. But every once in a while, you need a little more control over the shutdown process — especially when you have long-lived sessions, such as WebSockets or HTTP long polling.</p><p>The problem with long-lived WebSocket sessions is that the Application Load Balancer (ALB) starts to forcibly kill all “still active” connections once the draining period has elapsed. By the time the application receives a SIGTERM, the long-lived connections may have already been terminated by the ALB. This makes it impossible to close them gracefully on the application side.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*xR7HyhA0IEZdS410" /></figure><p>This doesn’t have to be a big problem. The long-lived WebSockets will be closed abnormally — which would lead to 1006 Abnormal Closure code on the server and the client. But that’s all. Clients will reconnect to another healthy task and continue to operate normally.</p><p>There may still be rare situations when you’ll want to do some housekeeping before or after the disconnect, or track real abnormal closures and service restart closures differently. Or perhaps the perfectionist in you simply does not want to flood clients with a bunch of 1006 codes during each deployment. (Note: If you use a custom close code, be careful with 1012 Service Restart, as this code is not fully supported by Microsoft Edge.)</p><p>To cope with this type of situation, it’s important to find a way to close connections gracefully. If Amazon Web Services were to notify the application about draining events, it would be possible to initiate the connection’s termination process from the application side. But unfortunately that’s not an option, so we need to explore other ideas. One possibility is constantly polling the target state with the <a href="https://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference/API_DescribeTargetHealth.html">DescribeTargetHealth API</a>. Another option is to introduce a <a href="https://docs.aws.amazon.com/lambda/latest/dg/welcome.html">Lambda</a> that triggers when the target state changes and notifies the application. We don’t use either of these approaches at Grammarly — they are both far from ideal.</p><p>The method we use to tackle this issue is to detach the ECS service from the load balancer. (Note: Unfortunately, if you already have an existing ECS service running with the attached load balancer, you will have to re-create the service to alter the configuration).</p><p>This brings us back to return to the original flow:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7nWEWJE_x7uoLsfojaBkXw.png" /></figure><p>By receiving a SIGTERM signal, the application can terminate all in-flight connections gracefully and shut itself down properly. (Note: In Java, a SIGTERM handler can be added with <a href="https://docs.oracle.com/en/java/javase/12/docs/api/java.base/java/lang/Runtime.html#addShutdownHook(java.lang.Thread)">Runtime.addShutdownHook</a>.)</p><p>So far, so good. We now have full control of the connection closure process. But since we have detached the ECS service from the ALB, we need a way to route and balance traffic to the service tasks. There are multiple ways to implement that. The choice depends on your infrastructure schema. For example, if you use <a href="https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html">EC2 launch type</a> for your service and host your instances in the auto-scaling group, the auto-scaling group itself can be <a href="https://docs.aws.amazon.com/autoscaling/ec2/userguide/attach-load-balancer-asg.html">attached to the load balancer</a>. Another approach would be to use a <a href="https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-discovery.html">DNS service discovery</a> so that tasks can be accessed throughout an internal domain name and ECS can handle the registration/deregistration of a task in the service discovery registry. Though this second approach looks promising, there is no easy way to route traffic from ALB to a domain name, and most likely you will have to introduce an intermediate proxy (something like Nginx) to route the traffic, and that will make your infrastructure even more complex.</p><p>We’ve come a long way and now have managed to get the balanced traffic to our application. But we do not want to route traffic to unhealthy or stopping tasks. To make sure we avoid doing so, we should look closely at those tasks. Once a SIGTERM is received, a stopping task has to turn off the health check endpoint and fail all health check requests for that load balancer to move the stopping target to the unhealthy state. It will require a wait of at least UnhealthyThresholdCount * HealthCheckIntervalSeconds (according to <a href="https://docs.aws.amazon.com/elasticloadbalancing/latest/application/target-group-health-checks.html">health check settings</a>) before the load balancer considers the instance to be unhealthy and stops routing traffic to it. It might be a good idea to wait even longer, as that will effectively introduce the connection-draining feature to the shutdown process. (Pay attention to <a href="https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html">ECS_CONTAINER_STOP_TIMEOUT</a>, which has a default value of 30 seconds but can be increased up to 10 minutes.)</p><p>We’re almost there, but there is one more thing to address. By detaching the load balancer from the ECS, the service task no longer gets killed and restarted by failing the load balancer health check (as was the case for the <a href="https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-load-balancing.html#load-balancing-concepts">native service load balancing</a>). Luckily this functionality can be easily added using the container health check (as configured in a <a href="https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_healthcheck">task definition</a>).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MVYYM-vam9wJehitO-DhXw.png" /></figure><p>Using this setup, we have full control over the application shutdown process, which allows us to handle connections termination on the application side.</p><h3>Conclusion</h3><p>In this article, we examined in depth the Amazon ECS service update flow and reviewed the pros and cons for some of the workarounds which may help in non-standard scenarios. This is a window into one method by which Grammarly can smoothly update our products to consistently deliver high-quality writing support to our millions of users.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=690d1aeb44cc" width="1" height="1" alt=""><hr><p><a href="https://medium.com/engineering-at-grammarly/perfecting-smooth-rolling-updates-in-amazon-elastic-container-service-690d1aeb44cc">Perfecting smooth rolling updates in Amazon Elastic Container Service</a> was originally published in <a href="https://medium.com/engineering-at-grammarly">Building Grammarly</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Under the Hood at Grammarly: Leveraging Transformer Language Models for Grammatical Error…]]></title>
            <link>https://medium.com/engineering-at-grammarly/under-the-hood-at-grammarly-leveraging-transformer-language-models-for-grammatical-error-2945b0672884?source=rss-d1e3c14169c8------2</link>
            <guid isPermaLink="false">https://medium.com/p/2945b0672884</guid>
            <category><![CDATA[deep-learning]]></category>
            <category><![CDATA[naturallanguageprocessing]]></category>
            <category><![CDATA[nlp]]></category>
            <category><![CDATA[research]]></category>
            <dc:creator><![CDATA[Grammarly]]></dc:creator>
            <pubDate>Wed, 07 Aug 2019 17:33:38 GMT</pubDate>
            <atom:updated>2020-01-02T04:23:26.290Z</atom:updated>
            <content:encoded><![CDATA[<h3>Under the Hood at Grammarly: Leveraging Transformer Language Models for Grammatical Error Correction</h3><p><em>Written by </em><a href="https://medium.com/u/3a216f2a1d07"><em>Dimitris Alikaniotis</em></a><em> and </em><a href="https://medium.com/u/5c9e8513c482"><em>Vipul Raheja</em></a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*-tl0Ip-sYG1YeB3z" /></figure><p><em>Read the original article and more on </em><a href="https://www.grammarly.com/blog/engineering/"><em>Grammarly’s new engineering blog</em></a><em>!</em></p><p>Over the past ten years, Grammarly has focused on building one of the world’s best writing assistants. One major aspect of this is grammatical error correction (GEC). It’s a core component of achieving our mission of improving lives by improving communication — from helping people craft an error-free social media post to supporting them in perfecting a cover letter for a dream job.</p><p>To this end, we have made tremendous progress toward building an AI-powered system that achieves state-of-the-art performance in correcting grammatical errors in English writing. Progress in GEC research has historically relied on training large machine learning models on vast quantities of annotated data. As part of our pursuit to improve the performance of GEC systems, we have also researched models that do not rely on these large annotated datasets but instead leverage language-modeling methods of natural language processing (NLP).</p><p>This is also the subject of a new paper from the Grammarly research team that appeared at <a href="https://sig-edu.org/bea/current">the 14th Workshop on Innovative Use of NLP for Building Educational Applications (BEA)</a> at the <a href="http://www.acl2019.org/EN/index.xhtml">Association for Computational Linguistics (ACL) conference</a> in Florence, Italy.</p><h3>An informal background of language modeling</h3><p>Let us begin with a simple linguistic fact:</p><ul><li>The cat sat on the mat.</li><li>The cat sit on the mat.</li><li>On the mat the cat sat.</li><li>On cat mat the the sat.</li></ul><p>Many people would be able to infer the intended meaning of these four sentences: there is a cat that’s sitting on a mat. Speakers of English would find the first option the most plausible, however. Why is this? The answer is not trivial — philosophers, linguists, psychologists, and cognitive scientists have long debated the answer.</p><p>Let’s first take the simplest approach and offer that English, like all human languages, follows some grammatical rules. These include:</p><ul><li>The object of the sentence follows the verb.</li><li>The subject and the verb must agree in number.</li><li>The article comes before the noun.</li></ul><p>Students of English tend to learn these rules very early on, either through explicit instruction or simple induction from being exposed to the language, and follow them throughout their lives. Rules of this kind are essential pieces of language and can tell us a lot about its evolution, its connection to other languages, and its learnability.</p><p>Though languages do tend to follow such rules, let’s take a step back and look at the problem of the cat on the mat from another perspective. Consider the following thought experiment, in which we should presume not to know how to write or speak English but do have access to thousands of books written in English. In this scenario, we might notice that words ending in -s tend to go before the word <em>sit</em>, while words without -s tend to go before <em>sits</em>. Because we don’t have any direct knowledge of English, we’re not aware of the rules governing this behavior. Even so, we can extract some statistical patterns that might help us construct the correct sentence. These might be:</p><ul><li>Words without -s are more probable with <em>sits</em> or <em>sat</em>.</li><li>There is a low probability of the word <em>the</em> following another <em>the</em>.</li></ul><p>These statistical properties of language are what we call “shallow,” in the sense that they take into account superficial regularities. In other words, they do not “understand” the meaning of the sentence but rather reflect some of its statistical properties. Even such shallow properties can effectively cover quite a few rules.</p><h3>What we did</h3><p>Would it be possible to identify some statistical patterns that could help us in correcting usage? It turns out that such patterns are quite powerful tools for distinguishing between correct and incorrect usage. In our paper, we explore the engineering point of view of how to do so with accuracy.</p><p>Let’s begin by examining at a recent trend in natural language processing: what are called Transformer models. The name might sound like something out of a sci-fi movie but refers in our research to models that go through enormous amounts of text and distill the linguistic knowledge into statistical patterns. They might, for instance, be given the following sentence with a blank:</p><ul><li>The cat sat on the __.</li></ul><p>The Transformer model will try to fill in the blank with the most appropriate word.</p><p>The model does not need to know what <em>mat</em> means, but based on the data it has seen and the statistical patterns induced, it can infer that it’s more probable to have <em>mat</em> in the blank than <em>Roomba</em>.</p><p>The task in itself is simple. Imagine you have an excellent memory, went over large amounts of text, and can remember exactly how many times you saw the sequence “sat on the mat.” It will have been many more times than you saw “sat on the Roomba.”</p><p>The Transformer models have another advantage, which makes them all the more powerful: they are capable of generalizing. Imagine that they have seen the word <em>cat</em> and the word <em>dog</em> appearing in similar sentences. Does this make the sentence “The dog sat on the mat” as probable? According to Transformers, it sure does.</p><p>Now the question becomes whether we could exploit such models to avoid having to enumerate all the possible rules in language. Could we do this for rules we cannot describe — or even use it for understudied languages for which grammatical rules have not been thoroughly documented? What we show in our paper is that we are indeed able to do so with high accuracy by merely taking into account different wordings of the same sentence:</p><ul><li>The cat sat on the mat.</li><li>The cat sits on the mat.</li><li>The cats sit on the mat.</li><li>The cats sat on the mat.</li><li>….</li></ul><p>Before we move on to our key findings, though, the critical reader might raise two valid questions. First, how does the Transformer know that <em>sit</em> and <em>sits</em> are related? Regarding this question, we will admit that, at this point in our research, we help the model out by including a large, automatically generated database of English words so the model knows that <em>sit</em>, <em>sitting</em>, <em>sat</em>, and <em>sits</em> are related.</p><p>A reader might also ask how we look for the most probable sentence. Do we look for all the possible alternatives? To this question, we would answer that we can’t enumerate all possible alternatives, as it would be too time-consuming. In practice, we scan the sentence from left to right — beginning to end — and try to facilitate the best possible choice at each point. This means that down the road there might be another layer of decisions to be made about problematic results, but it’s a trade-off between accuracy and speed.</p><h3>What we found</h3><p>What we find is that Transformers making such local decisions are able to reach high levels of accuracy, comparable not only to customized systems that follow hard-coded English rules but also deep neural networks specifically designed for carrying out this task. What’s more, because such systems only compare a few sentences at a time, they represent a scalable solution that can deliver corrections much faster than other systems.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*fOEiqxtcsWOXYFyC" /><figcaption>A comparison of Transformer language models (BERT, GPT-1, and GPT-2) against two recent similar systems on standard GEC datasets.</figcaption></figure><p>While the results of this method are promising, does this mean we do not any longer need rules or sophisticated systems? The answer is, of course, no. This methodology should in no way be considered a panacea for systems that aim to automatically correct ungrammatical sentences.</p><p>The best performance can be achieved using a hybrid approach that combines multiple methods — custom-made rules, deep neural networks, and language models, among others. Transformer models so far cannot capture errors as nuanced as more sophisticated methods. (For example, what happens if we need to introduce a new word to the sentence?) Still, despite shortcomings in these early stages, using Transformer models can capture linguistic usage at scale and aid such systems in delivering the best corrections possible.</p><h3>Looking forward</h3><p>Here at Grammarly, we are committed to improving communication, and a big part of this is correcting incorrect grammatical usage. By using cutting-edge technology, Grammarly continues to develop the ways it provides the highest quality corrections to our millions of users.</p><p><em>Dimitris Alikaniotis and Vipul Raheja are research scientists at Grammarly. Dimitris presented this research at the </em><a href="http://www.acl2019.org/EN/index.xhtml"><em>57th Annual Meeting of the Association for Computational Linguistics</em></a><em> in Florence, Italy, which took place from July 28 to August 2, 2019. The accompanying research paper, “</em><a href="https://arxiv.org/abs/1906.01733"><em>The Unreasonable Effectiveness of Transformer Language Models in Grammatical Error Correction</em></a><em>,” will be published in the </em>Proceedings of the 57th Conference of the Association for Computational Linguistics<em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2945b0672884" width="1" height="1" alt=""><hr><p><a href="https://medium.com/engineering-at-grammarly/under-the-hood-at-grammarly-leveraging-transformer-language-models-for-grammatical-error-2945b0672884">Under the Hood at Grammarly: Leveraging Transformer Language Models for Grammatical Error…</a> was originally published in <a href="https://medium.com/engineering-at-grammarly">Building Grammarly</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Part 1: How Grammarly tackles hidden complexity in front-end applications]]></title>
            <link>https://medium.com/engineering-at-grammarly/part-1-how-grammarly-tackles-hidden-complexity-in-front-end-applications-1b22b10a24d5?source=rss-d1e3c14169c8------2</link>
            <guid isPermaLink="false">https://medium.com/p/1b22b10a24d5</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[frontend]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[front-end-development]]></category>
            <dc:creator><![CDATA[Grammarly]]></dc:creator>
            <pubDate>Thu, 11 Jul 2019 15:54:37 GMT</pubDate>
            <atom:updated>2020-01-02T04:22:37.608Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Written by </em><a href="https://medium.com/u/c59bcb97bf84"><em>Anton Pets</em></a><em> and </em><a href="https://medium.com/u/2fe52066abf2"><em>Yaroslav Voloshchuk</em></a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kXadUFSi-I_u_jMc1eVEmg.jpeg" /></figure><p><em>Read the original article and more on </em><a href="https://www.grammarly.com/blog/engineering/"><em>Grammarly’s new engineering blog</em></a><em>!</em></p><p>Unsupportable spaghetti code. Scope creep. Instant legacy status for a new product the whole team <em>had</em> been excited about. Most engineers have a horror story about a project’s complexity being underestimated or misunderstood. But the damage from a spiraling project like this doesn’t always end with the last commit and deploy: the consequences can extend to ruined architecture, reduced team morale, and increased risk of employee attrition. And that can all happen before the project even ships, when there can be a risk of <a href="https://www.theatlantic.com/technology/archive/2017/09/saving-the-world-from-code/540393/">actual physical dangers resulting from malfunctioning software</a>.</p><p><a href="https://carlalexander.ca/what-is-software-complexity/">Complexity</a> is a constant in computer science, and there’s no one way to conquer it. The Grammarly engineering team has wrestled with it for years, and we’ve worked out methods for identifying it and reducing it, ensuring that our features are finished cleanly and efficiently.</p><p>This post details some of our battles with complexity and what we learned from them. By walking you through the development of three Grammarly features, we’ll showcase our systematic approach and leave you with several concrete ways of finding and addressing complexity in software projects — while also offering up some of our favorite outside resources. Our hope is that your engineering team can plan more effectively and unearth complexity at the beginning of the project instead of being surprised when it reveals itself too late.</p><h3>Real-world example: the Grammarly Editor</h3><p>When planning the creation of the Grammarly Editor, we anticipated complexity coming from needing to handle texts of varying lengths. Working with a user’s whole text can be difficult and can affect performance, particularly if the text is large, as often occurs in professional-level use.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7YJvMlfCYoigxrOH4jgfJw.png" /><figcaption><em>Sample document in the Grammarly Editor</em></figcaption></figure><p>One way to approach the Grammarly Editor would be to sync with the backend every time a user types a character. This would be one way of ensuring that the user is always seeing checked text. But an average writer types 120 characters per minute, and to optimize performance, it is better to group batches together. For that approach, we have three requirements to keep in mind:</p><ul><li>We want to manage UI lag while a user types while also considering how reacting to the user’s typing with immediate feedback could come across as an interruption.</li><li>Even if we pace feedback to match the rate desirable for a user, we still have to check the user’s text continuously for a smooth experience.</li><li>We have to save the text efficiently and not overwhelm servers with overly frequent requests.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wj6hY-Rp7aVYcYtsZht33Q.gif" /><figcaption>Delivering feedback while writing in the Grammarly Editor</figcaption></figure><p>These are what we’ve established as primary concerns for good user experience. However, our mission is to help people improve their written communication, so we do need to inform users about grammar mistakes and offer other suggestions for improving their text in a way that lets them react and learn. Alerting them to these mistakes alongside the text in progress adds the following complications:</p><ul><li>We have to show several animations without lag.</li><li>We must intelligently manage the appearance of alerts, showing them at the right time.</li><li>We need to calculate and manage error ranges in text.</li></ul><p>Beyond that, we also have to navigate the complexity that comes from network-related issues. For example, we use <a href="https://en.wikipedia.org/wiki/WebSocket">WebSockets</a> to communicate with the backend, which requires a constant connection to be maintained from the client side. On top of that, we have to deal with frequent network bottlenecks.</p><p>This is all from a single product central to Grammarly’s business. Whew!</p><p>We try to address this fairly common level of complexity by approaching it from different sides — a common but undervalued approach. All this complexity arises from one fairly straightforward function: processing and offering guidance on the submitted text. How can engineers hope to reduce complexity when the central functions needed from your product are so complex? Code problems are universal, but our work affects our users directly and consistently. Because of this, code problems can become human problems faster than in other systems.</p><p>Fortunately, there are ways, both theoretical and practical, to find the origins of complexity, to recognize it, and to deal with it in a consistent, effective way. Here’s how we handle this.</p><h3>Avoiding complexity assessment mistakes</h3><p>Complexity is an inherent part of any planning and assessing, and it only intensifies when you bring software engineering into the picture. We can’t avoid complexity entirely, but we <em>can</em> reduce its risks by keeping some things in mind — and ensuring that we really, fully understand the problem at hand. Here’s another example from Grammarly engineering.</p><h3>Real-world example: full-text search</h3><p>We received a task to create a feature that could perform full-text search on a set of documents within the Grammarly Editor. This proved to be far more complicated than we initially understood.</p><p>Unfortunately, when an engineering team is initially estimating the time it will take to finish a task, they are not always operating with a full understanding of the task at hand: they don’t take edge cases into account, they use third-party libraries, or they are basing their thinking on incomplete requirements. Even so, the primary source of software complexity is usually the inherent complexity of the problem.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*O8jsUoVi22VNZmiI" /><figcaption>Grammarly Editor search function</figcaption></figure><p>People tend to be optimistic, which can be an admirable trait in everyday life but a disastrous one in software engineering. For example, opening a window is a straightforward action for the user, so if we receive a requirement to create a window in the product, we may think it’s a pretty straightforward component to add. But how many different types of windows are there? And how many functions can they perform?</p><p>As a user, one doesn’t think, “I’m going to open a window of type 17, and clicking this button needs to update three database entries.” It just opens. But as engineers, trying to encode this as a program involves different methods of pulling the handle, updating handle state, and other details. Before we start working with complexity at the code level, we need to understand the task more fully. Without doing so, the process might look like this:</p><ul><li>Perform some planning and resource allocation</li><li>Choose the approach, architecture, and tools</li><li>Write code</li><li>Test</li><li>Deploy</li></ul><p>None of this is technically incorrect; the problems come when we follow those steps and begin to think that we’re at the point of having production-ready software — and only then take into account edge cases and requirements.</p><p>So for the search problem: we needed to ask the right questions while planning. In our case, we learned that the function should be able to search <em>all</em> documents, not only the visible ones. (For context, clients only have access to their first 100 documents, which is something we engineers <em>thought</em> was widely understood.) But uploading all the documents to memory would take too much time, so we realized we would need to perform a search on the server.</p><p>Once that aspect of the request was understood, more requirements appeared. We’d need to make sure the server search was fast enough. And perhaps the search would even need to work differently than initially assumed. Here’s our solution, which unearthed even more complexity:</p><ul><li>If the user has fewer than 100 documents, then we’d perform a front-end-only search.</li><li>Otherwise, we’d make two parallel searches — both client- and server-side — and show the server results as soon as they were available.</li><li>However, this solution creates an interesting edge case: a front-end search might show zero results, but then the user may suddenly see more results once the ones from the server are populated. To make this more user-friendly, we decided that if the front-end results are empty, we’d show a spinner until the server results appear.</li></ul><p>These snowballing requirements help our user, but they bring additional complexity to our architecture — particularly because we didn’t account for them from the beginning.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*YS5tvroVsJvPrUJZ" /><figcaption>Example of a spaghetti code diagram</figcaption></figure><p>Let’s walk back through these steps and call out some of the problems that arose. In the next section, we’ll explain each avoidable problem and how to prevent it.</p><p>Our realization that accessing more documents would require a server-side search and that this search would be too slow for our purposes was an example of <em>incorrect initial assessment</em>. Our plan to respond by searching on both the client and server sides, then merging them in real time, was <em>underestimating technological complexity</em>. The result — spaghetti code and a bloated timeline — would increase costs across time: <em>underestimating project complexity</em>.</p><p>These can all be catastrophic to a team striving for good software engineering practices. Fortunately, they’re all also avoidable with awareness and good process.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/480/0*Lchmilp6fBFzpxBr" /><figcaption>Debug duck</figcaption></figure><h3>Avoiding complexity catastrophe</h3><p>Before we write a single line of code, we try to describe the problem with as much detail as possible. We talk to colleagues, specialists, and non-specialists — and to the debug duck. Then we run requirements testing with engineers, ask how to break a feature, and brainstorm edge cases. We think about life cycles and how a feature will develop in a month or a year or more from now. We also look at how competitors do similar features and learn from their approaches. This helps avoid <em>incorrect initial assessment</em>. We ask questions until no new answers turn up. David Hogue’s talk <a href="https://www.youtube.com/watch?v=9hohuqj-yI8&amp;">“Simplicity Is Not Simple”</a> offers more ways to dig into a situation to uncover, categorize, and address hidden complexity, with examples of successful complexity reduction from his work.</p><p>To complement our questions, we use a variety of tools. Our designers not only draw but also make interactive product prototypes to ease implementation. In very complicated cases, we build real models, using prototype-quality code to simulate full functionality.</p><p>We’ve also had success using a large mindmap. When we were completely rewriting the Grammarly Editor, we gathered all of its features this way, which made iteration much simpler and ensured that we didn’t miss a single requirement. It also helps us to avoid <em>underestimating project complexity</em>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*GnjnweH6poTwmCkX" /><figcaption>Example of a product mindmap</figcaption></figure><p>If the product’s components use logic that is particularly complex, we typically also draw a state diagram (or statechart) with events and transitions. Here is an example of a state diagram of a standard alarm clock.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*v1QZUkQmHVXh1f9x" /><figcaption>State diagram of a standard alarm clock</figcaption></figure><p>Though the step seems deceptively simple, creating a state diagram is an effective exercise in understanding that state is anything but straightforward. We’ve found this to be a great way to avoid <em>underestimating technological complexity</em> — by not only documenting this area of complexity but also by ensuring that any lack of clarity or detail is deliberately and clearly eliminated before valuable engineering hours are allocated and used up.</p><p>We found these through research and experimentation, which we recommend you do within your team when creating your process.</p><p>Let’s look at these steps in action.</p><h3>Real-world example: the Grammarly Editor sidebar</h3><p>Before we begin coding, and after the intense research we do with SMEs and other stakeholders, we’ve typically created and abandoned about five different designs for the UI. There are two general categories of abandoned designs:</p><ul><li>Designs rejected by our UI designers or product managers</li><li>Designs that passed those reviews but were problematic to implement from an engineering point of view. Some are hard to implement in general, and some have just a few difficult edge cases with no UX solution</li></ul><p>After we have two ideas that are good enough to prototype, we use the <a href="https://en.wikipedia.org/wiki/Pareto_principle">80/20 principle</a>: How can we make 80 percent of a product in 20 percent of the time without architecting or testing? We then iterate until we as a team are happy with the result. In the case of the Grammarly Editor sidebar, we decided to use the sixth design as the basis for our product.</p><p>We then designed the architecture on a whiteboard and made an initial version of the feature to show a small number of real users. We did this four times, collecting and implementing feedback, and showing the new version to users to ensure we were on the right track.</p><p>Once we landed on a relatively stable version of the sidebar design, we began to create the animation, keeping in mind that smooth animation is critical for this feature to work. Our designer created an interactive prototype that covered 80 percent of our predicted uses, but we couldn’t implement the other 20 percent of edge-case uses without a real prototype.</p><p>We decided to use paper prototypes as seen below. The feedback we got from those helped us to finally implement the animation. But then we got feedback from our users: the motions in our 3D animation made them feel queasy — so we backed off and made everything much simpler and in 2D.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*Mdv-6cLb3N6OK2ax" /><figcaption>Physical prototyping of the Grammarly Editor sidebar</figcaption></figure><p>All of this happened before we wrote a single line of code meant for production. Since then, we’ve implemented and released the sidebar. We continue to get feedback, and we’re still actively working on improving it. However, by asking questions, gathering feedback, and collecting requirements beyond the obvious early ideas, we were able to work through a lot of the feature’s needs before using expensive coding hours and without forcing our users to become beta testers. The process was still complex, but it remained organized — and our code reflects that.</p><h3>Making friends with necessary complexity</h3><p>Programming essentially consists of composition and some work with complexity. With the use of basic math and logical operations, you can build any software system — if you can cope with the complexity. No matter what programming language you are using, you’re just combining smaller blocks into bigger ones until you get a program. It sounds simple, but complexity lurks even in that stripped-down description.</p><p>So no one can avoid all complexity — but it is possible to understand and account for it before diving into code. At Grammarly, we use some classic ideas from computer science to guide the planning and iteration we described above, which help us have an idea of how much complexity we can reasonably expect to reduce through that process. We can’t cover the entirety of the vast field of complexity in one post, but we can describe our view of the issue and detail a few high-level practices that have been effective for us in reducing unnecessary complexity in our engineering organization.</p><p>One way to define complexity is as a measure of the interaction of the components and the level of entropy in the software — i.e., how disorganized things are. In his 1987 <em>Computer </em>magazine essay <a href="http://www.cs.nott.ac.uk/~pszcah/G51ISS/Documents/NoSilverBullet.html">“No Silver Bullet — Essence and Accident of Software Engineering,”</a> Fred Brooks wrote that complexity comes from two places:</p><ul><li>From the task itself: the so-called essential complexity, which depends on the input and output of your task, and is caused by the outside world so cannot disappear or be reduced. We can only be aware of it and work with it. Think of our earlier example about the intersection of technical and behavioral needs in the Grammarly Editor.</li><li>From what we bring to the code: accidental complexity, the random component. This is what we are mainly struggling with. Our responsibility as software engineers is to write working code with minimal accidental complexity.</li></ul><p>Within the code itself, the two types of complexity are coupling and cohesion. Coupling measures how spaghetti-like your code is: to what extent the components are related to one another, how many dependencies you have. One goal of good early planning is to reduce this as much as possible. Cohesion shows how focused your components are and whether they have a clear purpose or blurred functionality. The lower the cohesion and the more diffuse your components are, the stronger the connectivity, which requires more extensive parameters and other clarity-reducing efforts. Our task, when working with the code, is to lower the coupling and increase cohesion. (Daniel Westheide goes into greater depth on these ideas in <a href="https://danielwestheide.com/blog/2018/12/07/the-complexity-trap.html">“The Complexity Trap: Think Before You Leap.”</a>)</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*J95rcLjBS3C-zPvX" /><figcaption><em>Cohesion vs. coupling</em></figcaption></figure><h3>Toward a less-complex future</h3><p>The great and terrible thing about software engineering is that there are few simple problems. However, even the most complicated projects can be made easier to understand and complete by taking the right steps at the right time — ideally before writing any code. Ask questions, account for edge cases, and always assume there is more to be understood.</p><p>Complexity manifests itself in our code at different levels of abstraction. The main challenges belong to the realms of structural and behavioral complexity types. Our next post will complement this one by diving into some of the more classic computer science principles and best practices for identifying and avoiding complexity. Until then, let me know if you enjoyed this article by hitting the applause button or leaving a comment below!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1b22b10a24d5" width="1" height="1" alt=""><hr><p><a href="https://medium.com/engineering-at-grammarly/part-1-how-grammarly-tackles-hidden-complexity-in-front-end-applications-1b22b10a24d5">Part 1: How Grammarly tackles hidden complexity in front-end applications</a> was originally published in <a href="https://medium.com/engineering-at-grammarly">Building Grammarly</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>