DEV Community: Nicolas Trahan

The big idea from A Philosophy of Software Design

Nicolas Trahan — Fri, 21 Apr 2023 18:46:50 +0000

What makes a certain software design better than any other? In A Philosophy of Software Design, John Ousterhout offers a simple but profound idea: the goal of software design should be to minimize complexity as much as possible, with complexity being defined as “anything related to the structure of a software system that makes it hard to understand and modify the system”. It’s as simple as that! But why should this be our goal? As the author explains, as a system grows and complexity accumulates, “it becomes harder and harder for programmers to keep all of the relevant factors in their minds as they modify the system. This slows down development and leads to bugs, which slow development even more and add to its cost.”.

I think this is extremely well put, and I love this definition of complexity because it’s entirely centered around human beings. I think it can be easy for engineers—but especially for managers!—to focus more on the objective aspects of the systems we work on: whether they work as specified, whether they’re performant, etc. But we can’t ignore this critical human idea of complexity, because if left unchecked, creeping complexity will gradually slow down the speed at which we can fix bugs and add features within any given system, correspondingly increasing developer frustration. Slower development time means greater costs, and increased frustration means higher developer turnover, so minimizing complexity should be something everyone at our organizations, from developers all the way to CEOs, should be concerned with.

The author builds on this simple definition of complexity to define the complexity of an overall system as the sum of the complexities of each part, weighed by the fraction of time that developers spend working on that part. At first glance it didn’t seem to me like that definition was an accurate representation of what most developers actually mean when they say that a system is complex. But on further thought, we wouldn’t for instance consider an otherwise simple system that makes use of a modern relational database as “complex”. Yes, the database system itself is extremely complex, but since we don’t need to peek inside and contemplate its inner workings in order to make use of it, its complexity has essentially been trapped; therefore the overall system certainly feels simple. So on further thought, I think this definition is actually brilliant, and an incredibly useful way of thinking about the complexity of a system and the quality of its design. Reduce this measure for a given system and it will become easier, more pleasant, and more efficient to maintain.

With this powerful definition of complexity in hand, the rest of the book looks at various ways that complexity can creep into our software systems and offers specific tips on how to fight these various manifestations. I think my single favorite one of these might be the idea of deep versus shallow modules: deep modules hide a lot of functionality behind a relatively small interface, and shallow modules are the opposite. The author explains that “Module depth is a way of thinking about cost versus benefit. The benefit provided by a module is its functionality. The cost of a module (in terms of system complexity) is its interface.” I never thought of interfaces as adding complexity to our systems, but of course it’s obviously true: interfaces need to be studied to be understood and made useful, just like any other parts of our systems. And what this means overall is that deep modules should be preferred over shallow ones. In some cases, the cost of a module, its interface, might even be outweighed by its benefit, the complexity it hides, meaning it probably shouldn’t exist at all! It also means that we shouldn’t feel compelled to automatically start slicing up longer functions or modules into smaller pieces just because of their length. If they’re long but still feel rather easy to understand, we might make them overall more complex by slicing them up, since every new piece now comes with the burden of an interface that adds complexity to the overall product.

Here’s a nice little chart from the book that illustrates this idea of deep versus shallow modules:

There’s a lot of other great ideas and tips to reduce complexity discussed throughout the book, for instance:

Chapter 3 discusses the difficult problem of knowing when you should be focusing on design work (”strategic programming”) versus when you should be focusing on just getting something to work (”tactical programming”). I love and wholeheartedly agree with the following quote from this chapter: “the ideal design tends to emerge in bits and pieces, as you get experience with the system. Thus the best approach is to make lots of small investments on a continual basis”.
Chapter 5 argues that the most important technique to achieve deep modules is “information hiding”, which is knowledge that is “embedded in the module’s implementation but does not appear in its interface, so it is not visible to other modules”. The part about information not being visible to other modules is critical, because if the information isn’t hidden, the complexity hasn’t actually been trapped. This can manifest itself in what the author calls “information leakage”, where information within a module is actually duplicated outside of it, contributing to complexity. I think these ideas of trying to hide as much information as possible within our modules and of preventing information leakage are highly useful to keep in mind while designing software.
Chapter 11 promotes the interesting idea of considering multiple designs for each major decision: “you’ll end up with a much better result if you consider multiple options for each major design decision”. It’s not something I have the habit of doing, but I can see how it would help produce better designs: I’ll have to give it a try!
I love Chapter 12 because it provides a rebuttal to common excuses for not writing comments, excuses that I’ve heard myself many times before. I agree with the author that comments can make systems much easier to understand and therefore maintain, and that they’re worth investing in.
The title of Chapter 13 itself is a simple yet powerful idea we should always keep in mind when writing comments: “comments should describe things that aren’t obvious from the code”.
Chapter 14 is interesting because it discusses the critical problem of choosing names for identifiers! Of course choosing names is an important aspect of reducing complexity, since good names can obviously make our systems easier to understand. But unfortunately it’s notoriously hard to do, as the famous quote attributed to Phil Karlton says: “There are only two hard things in Computer Science: cache invalidation and naming things". So it’s nice to have a chapter dedicated to this topic.

There are a few pieces of advice in the book I didn’t necessarily agree with though. For instance, in Chapter 15 the author recommends that you write your comments at the beginning of the design process, before writing any code. I just can’t see myself following this advice. It reminds me of test-driven development, where developers are encouraged to write tests before any implementation code, which I also don’t think is practical or useful most of the time. I think writing a good description of a design is a difficult and time consuming activity, and in practice as developers we need to actually write some code and experiment with our design ideas to see if they even work. In other words, our designs should probably evolve quite a bit before we settle on something we’re willing to commit to (this idea of experimenting with multiple design options is even recommended in the book itself, in Chapter 11, as I mentioned earlier). I think it would be quite inefficient if we had to write and evolve our comments every time we changed our design in the early experimental phases: better, in my opinion, to wait until things have settled down a bit.

Apart from that, I think the book would benefit from a broader discussion on automated testing and how it might affect the design process. It does devote a chapter to the tension between performance and complexity, yet a similar tension clearly exists between testability and complexity. Considering how important automated testing is to modern software development, a chapter on the topic would be useful.

Overall, A Philosophy of Software Design offers a powerful mental model and a North Star for guiding our software design decisions. I highly recommend it to software developers at any level of experience.

Fast feedback loops in software developement: they matter!

Nicolas Trahan — Tue, 26 Oct 2021 03:29:31 +0000

There’s been some drama as of late with regards to Microsoft’s decision to remove the hot reloading capability from .NET command line tools for the upcoming .NET 6 release.

For those who don’t know, .NET is a Microsoft-led open-source and cross-platform software framework that supports a variety of languages, most notably C#, and a variety of application types, such as web applications/services, command line tools, and desktop and mobile applications. The feature in question, .NET Hot Reload, allows developers to apply code changes to applications they’re debugging without having to restart them. It’s similar to React Fast Refresh or Hot reload in Flutter.

So what happened exactly? On October 20th, Microsoft announced that hot reloading would only be available through Visual Studio for Windows in the upcoming November 8th general availability release of .NET 6. This means that developers using command line tools to develop for .NET—those using Visual Studio Code on any platform, for instance—wouldn’t be able to benefit from hot reloading once they switched to the GA release. This announcement was especially surprising and frustrating since this feature had been available in preview for a while, seemed to be working decently well, and was pulled so close to the release date.

The backlash was strong and immediate: see the coverage by The Verge or by Dustin Moris Gorski, a .NET developer, for instance. Thankfully though, Microsoft listened to the .NET open-source community and soon reversed course, deciding to allow the feature to be included in the final release after all. (also see this article by The Verge for more details on the reversal)

Why were .NET devs so vocal and angry about Microsoft’s decision? Clearly, Microsoft handled the situation very poorly, but no doubt the frustration was amplified because of how powerful and important this feature is.

I can relate. In my current project at work, I’m working on an ASP.NET Core MVC application with an HTML/CSS/Javascript frontend, using Visual Studio on Windows as my IDE. With this setup, whenever I'm debugging the application and I edit any file that isn’t a view, the entire application needs to be stopped and restarted before I can see my changes in action. This takes a little while, but even then I'm still not done! Now I'm staring at the first page of my site and all the inputs are blank, so now I have to navigate back to where I was before and enter all my data back into the page again.

But the impact on my productivity goes beyond the time that's wasted getting back to the previous state in my application every time I make some code changes. It’s also the fact that the whole process is distracting and might take me out of my flow. By the time I'm finally back to where I was before, I have to ask myself, “What was I trying to do again?”. Sometimes I can’t remember! I need to get refocused, a huge waste of mental energy. Being able to simply save my source code and see the changes applied instantly would allow me to keep my focus and preserve my limited supply of mental energy, allowing me to be much more productive.

In general, hot reloading can be seen as a tool to speed up what some people call the “inner loop”, the “inner dev loop”, or the “launch/debug/update loop”, which is the process you go through repeatedly in development of making code changes and seeing/testing the resulting application. So what’s the moral of this story? Having a fast inner loop can greatly boost your productivity as a developer. Which by the way is something you might have realized if you've ever worked in a dynamic language like Javascript, PHP, Python or Ruby. And in my opinion, I'd actually say that their ability to provide fast inner loops have always been one of the main, if not the main selling points of dynamic languages. But I digress… happy coding and get that fast inner loop if you can!

Cover photo by Tine Ivanič on Unsplash

A React multi-step form

Nicolas Trahan — Wed, 02 Jun 2021 22:15:06 +0000

There's a ton of HTML multi-step form examples out there: see https://csshint.com/multi-step-html-forms/ for instance. So why create another one? Simply put, I couldn't find a form that satisfied my two main requirements:

1) Responsive. The form should look good on a phone, a desktop, and everything in between. It's 2021 and most web traffic now goes through mobile devices, so making your pages responsive should be a top priority.
2) It should be easy to change the number of steps, and the form should look good and stay responsive regardless of how many steps you have.

I was also looking for the following:
3) You choose be able to choose an icon to represent each step.
4) Clicking on a step indicator should navigate to that step.

Here's what I came up with:

The labels will disappear when there isn't enough horizontal space for them, but the form isn't smart enough to figure out the perfect breakpoint on its own: you'll have to manually specify that value in multi-step-nav.css.

Why add next and previous buttons in each step instead of reusing the same buttons everywhere? Doing it like this actually helps with the tabbing behavior: if you've tabbed to a next/previous button and press Enter, tabbing again will move you to the top of the new section, instead of tabbing out of the form towards the bottom of the document.

There's one accessibility feature I couldn't seem to figure out, however. When using NVDA (the most popular desktop screen reader according to the latest WebAIM survey) in browse mode, using the down arrow after pressing the Next or Previous button won't start reading at the top of the newly selected section. Anyone out there know how to fix this? 🙂

Cover photo by Kelly Sikkema on Unsplash

No, don't mock the Redux store!

Nicolas Trahan — Sun, 03 Jan 2021 20:31:33 +0000

As a side project, I’m currently working on a Chrome extension built using Create React App, Typescript, and the Redux Toolkit. For testing, I’m using Jest (set up for me by Create React App) and React Testing Library. Recently, I ran into a weird problem with my test suite: an assertion that a certain function was being called was failing, even though I knew for a fact that it was, indeed, being called. Here’s the code:

const proceduresAsAny = (procedures as any)

test("Add bookmark inside works", async () => {
    const createBookmarkNode = procedures.createBookmarkNode,
        createBookmarkNodeMock = jest.fn()

    proceduresAsAny.createBookmarkNode = createBookmarkNodeMock

    user.click(screen.getByTestId("folder-menu-add-bookmark-inside"))
    expect(createBookmarkNodeMock).toHaveBeenCalledTimes(1)
    const expectedArgs: chrome.bookmarks.BookmarkCreateArg = {
        parentId: "2.1",
        title: "New Bookmark",
        url: "https://google.com"
    }
    expect(createBookmarkNodeMock).toHaveBeenCalledWith(
        expect.anything(),
        expectedArgs
    )

    proceduresAsAny.createBookmarkNode = createBookmarkNode
})

How did I know the mock function was actually being called? Simple, by giving it an implementation that would log to the console:

createBookmarkNodeMock = jest.fn(
    () => console.log("calling createBookmarkNodeMock!")
)

Here the Jest console was indeed printing "calling createBookmarkNodeMock!". So what gives? Why was the assertion failing?

Turns out the issue was async-related. Indeed, the button’s click event handler wasn’t just changing a component’s state or dispatching a simple Redux event, it was dispatching an async thunk that contained an await, meaning that everything that followed the await in the body of the thunk would be run after my test function finished running. Not too useful when I’m trying to test the effects of that button click!

So what’s the solution? All the advice I was finding online was saying the same thing: mock the store! Even the official Redux docs were saying that (see https://redux.js.org/recipes/writing-tests#async-action-creators). Now that’s cool and all, but there’s just one problem with that: I don’t want to mock the store! I’m trying to write a test that shows that my function is being called in a specific way when a certain button is pressed. I don’t care if that’s being done by sending a certain event to the store. In fact, I don’t even care if Redux is used at all! As long as my function ends up being called, I’m happy. So how can I write such a test?

The solution I found was pretty simple: React Testing Library’s waitFor function. waitFor will repeatedly call the given function until it doesn’t throw an error. So all I needed to do to get my test working was to replace this line:

expect(createBookmarkNodeMock).toHaveBeenCalledTimes(1)

With this:

await waitFor(() => 
    expect(createBookmarkNodeMock).toHaveBeenCalledTimes(1)
)

Is there a better way of accomplishing this without using waitFor? Do you disagree and think I should actually mock the store? Let me know in the comments!

Bonus: why is my mock OK?

In not wanting to mock the Redux store here, I’m certainly not saying that all mocks are bad. In the test shown earlier, for instance, I’m mocking a function that calls the Chrome API to create a bookmark node. I don’t want to actually call this function in my tests because 1) Setting up an environment where I can call this real API is complicated, 2) I’m very confident that the feature I’m testing is implemented correctly if the system actually calls the mocked function in the way that the test describes, and 3) I expect a test using the real Chrome API to be slower than the one using a mock. For these reasons, I’m happy to mock out the createBookmarkNode function (and in fact, I created this function specifically because I wanted to mock it out).

Cover photo by Wei Pan on Unsplash