Nasa's Laws of Writing Readable Code

Do you have what it takes to write code for NASA? Well, let's find out. Imagine this, you're trying to understand a function and as you're reading through the code, you're noticing multiple levels of indirection, which in turn is causing you to need to jump deeper into a tree of files and functions, ultimately putting you at someplace different entirely. This is a terrible code reading experience, right? By the time you reset back to the original function that you were trying to understand, maybe you've lost track of what you were trying to understand in the first place. But, what's the alternative? Well, it's to inline everything. This inlining should give the reader a more linear code reading experience, which should make it easier for people to read through and understand this code, right? Well, not really. You see, although we do have a more linear viewing experience, we now have to understand the guts of an entire chain of what were originally function calls every time we look at this function. That's right. You have to understand every detail every time you look at it. When in reality, you actually don't need to know about most of the implementation details to understand the original function. In fact, according to NASA, excessively long functions are often a sign of poorly structured code. The idea is that each function should be a logical unit in the code that is understandable and verifiable as a unit. But, a unit that spans multiple pages usually is comprised of multiple responsibilities. And yes, this does result in some levels of indirection. But, it should be clear now why that's better than the alternative. Let's consider an example where we take some immutable data from sub source and create what is essentially a processing pipeline to process that data. We'll create a variable for the resulting processed data that's scoped to the main function. We'll then pass references to that variable to the two processing functions. So far, so good, right? But, wait. What if Joe Schmo comes along and adds some logic that causes unintended side effects to the processed data that aren't intended to be part of the pipeline? Since the processed variable's lifetime is the run time of the entire main function, there are plenty of opportunities for Joe Schmos to come along and introduce unintended side effects. Not to mention, there's even the potential for some race conditions to pop up if concurrency is introduced, which is why NASA requires its developers to declare all data objects at the smallest possible level of scope. The rationale being that if there's a need to diagnose an object's erroneous value, reducing the data object's exposed surface area makes it easier to diagnose the problem. We can narrow the scope of the processed var to individual function calls by passing it by value. Now, we're passing copies of the original processed variable to the process functions. Finally, for the result, we just return the resulting value, which is then passed to the next process in the pipeline. The chance for side effects and race conditions and the level of debugging complexity increases as variable scope increases. So, it's best to minimize variable scope whenever possible. Similar rationale can be applied to data object access. For example, let's imagine we're writing out some logic that should be encapsulated within a specific package. We decide that putting a comment above the method informing people that it should only be used locally is sufficient because people are smart, right? But, then that boy Joe Schmo comes along and let me just say that brother doesn't read comments. A week or two down the line, we start to see the usage of this method pop up throughout the code base increasing the exposed surface area. One day, the original developer decides to adjust the method's interface not knowing that Joe Schmo has basically spread this method throughout the code base like the plague. To the original developer's surprise, his update to the method's interface has broken various parts of the code base. But, is this our boy Joe Schmo's fault? No. Similar to the previous example, we want to reduce data object's exposed surface area and we can do this if we make variables and

functions private or protected whenever possible. This minimizes accessibility, which in turn reduces the code's exposed surface area. And that's going to be it for this video. If you found this information helpful, don't forget to leave a like and subscribe if you haven't already and I'll see you in the next one.