Forem: Hudson Burgess

Do you practice TDD?

Hudson Burgess — Sat, 17 Nov 2018 15:50:22 +0000

If so, what made you want to start?

If not, why not?

How to systematically determine requirements?

Hudson Burgess — Tue, 24 Jul 2018 15:37:05 +0000

My team has a serious problem with forgetting seemingly obvious requirements. The 1-2 weeks before a release are full of "oh wait, we forgot about x. But it's an easy change, no big deal." Simple omissions are bound to happen, but by the time we release, the list of omissions we caught is usually bigger than the list of initial requirements.

What's a good starting point for systematically determining requirements for new features up front?

Questions to consider:

are there any checklists you use?
are there any particular areas where more requirements are forgotten than others? (ex. security, UI layout, etc.)
any useful / widely accepted books addressing this subject?
have you been on a team that successfully addressed this problem; if so, how did you fix it?

Making an Architectural Decision: A Live Example

Hudson Burgess — Mon, 23 Jul 2018 13:32:47 +0000

I'm literally writing this to work through my thoughts, so I thought I'd share.

Framework: Angular + ngrx

Scenario: Your application is able to generate a particular type of report. Any user can run and see a summary of said report, but they need to pay x amount to see the whole thing.

Two things need to happen here:

The user has to pay to unlock a particular report.
If that transaction completes successfully, the report needs to be marked as "unlocked."

We could do all this sequentially. Make the payment API call, then make the unlock call. But that might involve duplicating some existing logic, and it might force me to create some awkward "payment + report" object.

We could also make one of those actions a side effect. But which one?

is payment a "pre" side effect of unlocking the report?
or is unlocking the report a "post" side effect of paying for the report?

The former seems to make more sense. The end goal is unlocking a report, not spending money, so let's say unlocking the report is the "main" control flow here.

But the payment must succeed for the report to be unlocked. So is it really a side effect? Shouldn't side effects should be independent of the thing that triggered them? Perhaps the side effect idea isn't so great.

Well, I have @ngrx/effects. As much as I hate using it as an API wrapper (re Stop using ngrx/effects for that), it's a useful way to compose API calls from different services. Just because the library has "effects" in the name doesn't mean it has to be used strictly for side effects. We're certainly not restrciting it to that kind of usage right now. (Maybe in the future I should alias @ngrx/effects with a different name so our particular usage makes more sense?)

I guess I'll do that. Use the existing payment logic, write an unlock() service method, then use @ngrx/effects to chain them together.

Inspired by DHH's "On Writing Software Well" video series

How much should you refactor names when domain terminology changes?

Hudson Burgess — Tue, 17 Jul 2018 11:16:57 +0000

This is hard to explain in the abstract, so here's a hypothetical scenario:

You're building an app to manage inventory for a store that sells computer monitors. One day, the store decides that in the future monitors will be called "displays." Your managers promptly commit to this terminology change in conversations with you, and the marketing team ensures that all of their content reflects the change too. To the company, this change in terminology is important.

As a developer and a software craftsman, should you:

refactor all occurrences of monitor in your code to display (in class names, variable names, folder structure, etc.) to keep the terminology consistent?
leave the names alone because only the devs will see them, and the mismatch in terms will probably not cause any confusion?
something else?

How much should you refactor names when domain terminology changes?

Good first steps for a JS style guide?

Hudson Burgess — Sun, 03 Jun 2018 23:39:54 +0000

Right now I'm essentially the only frontend dev at my company, but we have plans to bring on one more (sometime soon, I think? ¯\(ツ)/¯). With that in mind, I'd like to start writing some sort of JS style guide / best practices doc. What are some good first items to include?

Should we wrap critical built-in modules?

Hudson Burgess — Fri, 05 Jan 2018 17:52:28 +0000

I've spent the last two weeks migrating one project from Angular's deprecated Http module to the new (more elegant) HttpClient. Two weeks -- in my opinion that's way too much maintenance time on a single layer of the app. I encountered something similar in the fall with Angular Material.

Which brings me to the question: should we wrap critical built-in modules to avoid this kind of massive overhaul?

While Uncle Bob suggests that we should avoid concrete dependencies where possible, you'd think that concrete dependencies on the framework itself would be okay. But this HttpClient debacle is proving otherwise.

Additional follow-up question: If / when we should put our own interface around critical modules, how do we define "critical?" What sort of modules warrant this kind of architecture?

Running on Fumes: Some Small Productivity Tricks

Hudson Burgess — Thu, 14 Dec 2017 00:00:00 +0000

The past week of work has been unusually long and tedious. Just wanted to share a few small tips I’ve been using to power through it:

1) Listen to the same thing on a loop

I picked this up from Tim Ferriss. Apparently, several top performers listen to the same song on repeat when they need to stay focused. I find that one song gets old pretty quickly, so I loop an entire album instead – right now, The Shape of Colour by Intervals. It’s energizing, has zero lyrics, and all the tracks sound similar enough that they flow together into one 34-minute opus (turning on cross-fade helps too).

2) Ignore the time

Nothing makes a long day worse than thinking about how much longer it’s going to be. I’ve removed the clock from the menu bar on my computer and keep my phone out of sight.

3) Write down what you need to do in small steps

Separate what you need to do from how you actually do it. This gets all the racing high-level thoughts out of your head so you can prioritize and execute. You’ll be surprised how much more efficient and effective this makes you, especially if you’re tired.

For the developers: if you’re having a hard time with a complex function, use comments or pseudocode to outline it first. If anything, you’ll probably write cleaner code with this approach!

4) Switch tasks for a few minutes if your brain really gets fried

Guess where this post came from…

5) Don’t let yourself totally stop working

Even though I’m taking a break by writing this, I’m still producing something. Keep up the little bit of momentum you do have. The sooner you finish what you need to do, the sooner you can put it away and forget about it. Fight to the finish.

What heuristics do you use when developing a frontend testing strategy?

Hudson Burgess — Tue, 05 Dec 2017 15:50:57 +0000

I'm currently on an Angular project with a decent sized test suite (~1000 tests), but it takes a long time to run and misses a lot of critical bugs -- I want to take a more nuanced approach.

On a broad level: what's your frontend testing philosophy?

If that's too vague, here are some more specific questions to consider:

What are your percentages of unit tests / integration tests / end-to-end tests?
Are there good quantifiable metrics for how long a (unit) test suite should take to run?
In terms of time spent on production code vs. tests, when is writing a challenging test not worth the effort (especially for E2E tests)?
When, if ever, is it okay to remove tests for stable code?
Do you split your test suite into different groups of tests? If so, how, and when do you run each group?

Code Like a Conversation: Basic Levels of Abstraction

Hudson Burgess — Thu, 19 Oct 2017 00:00:00 +0000

Consider the following conversation:

* at le Starbucks *
Friend: “Hey Hudson! What are you up to today?”
Me: “Not much, it’s an easy day today. Just working on a simple web app. I’ll probably grab lunch with some friends this afternoon and read a bit this evening. What about you?”
Friend: “Sounds fun. A few friends and I are going to see <recently released movie> tonight; do you want to come?”
Me: “Sure, I’ve been wanting to go see it.”
Friend: “Great! I’ll text you the details later.”

Ignoring the fact that I dislike staring at screens outside of writing / programming, that’s a conceivable conversation. Now consider this one:

* at le Starbucks *
Friend: “Hey Hudson! What are you up to today?”
Me: “Quite a lot. I got out of bed at 4:23am this morning, cooked breakfast and showered, realized I needed gas, drove to the gas station, swiped my debit card and entered my pin, filled up the gas tank, and went to work. Now I’m taking a break from editing line 105 of search-form.component.ts on my current project. I’ll probably grab lunch with some friends this afternoon, then go home and read with a cup of decaf coffee made in my French press.
Friend: “Sounds fun. A few friends and I are driving to the theater to purchase tickets for <recently released movie>, find seats in the theater in which it’s playing, then fixate our eyes on the screen therein until it ends; do you want to come?”
Me: “Sure, I’ve been wanting to go to the theater and watch it.”
Friend: “Great! I’ll send you the details via SMS later.”

Imagine if every conversation were like that (the horror…)

The first interaction is easy to follow because it stays at the same level of abstraction. Work, eat lunch, read, see a movie – these are high-level, simple statements about what my friend and I are doing. The second interaction is hard to follow because it uses several different levels of abstraction. 4:23am and using SMS are very low-level, specific details about how I did something; getting lunch and mentioning a few friends are descriptive and don’t involve details.

Our code should look like the first conversation and stay at a consistent level of abstraction. Instead, it often looks like the second. It forces the reader to context switch constantly and makes understanding the code needlessly difficult.

To help you refactor the “conversation 2 kind of code, here are 3 levels of abstraction that I’ve been using recently.

1. The primitive level

Ints, strings, booleans, pointers, etc. Functions and methods that operate on primitive types, properties, or class members are very low-level. Put another way, these functions should do only the “grunt work of the application. Working at this level can get a little dull because it’s usually easy – that’s probably a sign that you’re doing it right.

2. The problem space level

This depends on what you’re building. In general, the problem space level operates on objects in the realm of your client. For instance, if you’re building a library application, the problem space level might contain Books, Patrons, ConferenceRooms, and Computers. If you’re building a course registration system, the problem space level might contain Courses, Professors, and Classrooms. This is probably the lowest level of abstraction you’ll use when talking to your client.

The problem space level should consist of classes that simply group related values and functions. Classes shouldn’t need to talk to each other very much; that’s what the component level is for.

3. The component level

Components operate on items from the problem space level. To use the library example again, a CheckoutComponent might create a Checkout record from a Patron and a Book. To use the course registration example, a SignUpForm might allow a Student to sign up for a Course. In general, the component level does the interesting work that makes you money.

Conclusion

I realize this will be an almost childish review for some people, but thinking in these three concrete levels has helped me tremendously lately.

Are there additional levels of abstraction you tend to use? Different abstraction approaches altogether? Let me know.

The Holy Grail of Good Software

Hudson Burgess — Wed, 27 Sep 2017 00:00:00 +0000

The worst part of development

Building software requires so many steps in parallel: writing code, unit testing code, some manual testing, occasionally hopping over to Postman, three Stack Overflow tabs, the “asynchronish” Slack messages (grr)… you get the point.

We know from experience that just writing code demands a huge amount of attention and deep thinking. Every frustrated Google search and every rebuild-and-try-again chips away at our mental resources. Every “am I doing something wrong? distracts our colleagues. Every pull request that gets sent back for changes (needed as the changes may be) halts progress on another issue and derails a valuable train of thought.

So why is our collective response to accept that development is a messy process, add another monitor or two, and throw some line about “multitasking in the job description (which was probably already badly written anyway)?

How on earth do we expect to write – to design – good software like that?

180

What if we didn’t have to multitask to that extent?

What if we didn’t have to cobble together our understanding of an API from Slack threads and Postman experiments?

What if we were confident enough to only download official docs and work offline? (Psst… DevDocs…)

What if we never manually tested our code before we shipped it?

The Holy Grail

Maybe I’m nuts. Maybe this is too lofty a goal.

Except that all of those things are possible. Force more efficient communication. Document your code, whether it’s self-describing or needs another doc. Study your framework. Use automated build tools. And for the love of everything holy, write better tests. None of it is hard.

I dare you: the next time you have to fix a bug… don’t run your app.

If you’re scared to push code without running it manually, you don’t have a good enough support system. Period.

Whether that support system is pair programming, more focused coding sessions, comprehensive tests, robust build pipelines, better infrastructure, or better engineers (or all of the above), I could care less.

Bugs will still happen. But you’ll spend less time fixing them. And less time introducing them in the first place.

Be the engineer you wish you had.

Set an aggressively high bar, and do not back down.

Scaffolding: Another Benefit of Clean Code

Hudson Burgess — Fri, 22 Sep 2017 00:00:00 +0000

Imagine this scenario: you’ve been asked to build a particular feature that depends on someone else’s work. Maybe that work is happening within your team, maybe not. Either way, it needs to be done as quickly as possible. What do you do?

This has happened to me more than once in the past few weeks. My solution?

Don’t worry about it. Just write good code around it.

Two clean coding practices in particular can help us:

Breaking things into small pieces: This makes it easy to isolate implementation you don’t have yet, whether you need it from someone else or you simply haven’t figured out how to do it yet.
‎Testing: code that’s broken into smaller, independent, more manageable pieces is also easier to test, both in isolation and integrated. This way, when new code shows up, you can test it quickly and have confidence that it’ll play nicely with your existing work.

Lots of CLI tools (ex. Angular CLI, Rails generators, etc.) already scaffold around code you don’t have yet. Why don’t you do the same thing yourself?

7 Reasons You Should Be Using Test-Driven Development

Hudson Burgess — Tue, 08 Aug 2017 00:00:00 +0000

If you aren’t familiar with it, test-driven development (TDD) is a software development practice where you write tests before you write application code.

TDD is something most computer science students are taught, but are never actually required to use. And you can get away without doing it for most of your coursework. (I have some thoughts on that here.)

At any rate:

Good tests make good documentation – both for you and anyone who might come onto your project later. Test frameworks like Jasmine and Mocha read like plain English. Name your tests in a way that describes the tested function’s behavior in a particular circumstance.
You’ll code faster. Even if writing a correct function implementation is difficult, pre-written tests will give you a clear target to hit.
You’ll code correctly faster. Keep your test runner open to get continuous feedback on your work. This will get you to a correct implementation faster than coding an entire module at once and then testing it.
You won’t forget to write the tests. Code without tests should make you uneasy, period. A comprehensive, passing test suite is reassurance to you and other developers that your code (probably) won’t break.
It provides a solid starting point for later work. Similar to #1. Also, if you pick a project back up after a few months, you’ll forget how most of the code works. Tests can be a reminder, and a tested code base can be a fallback if you suddenly break things.
It pushes you to write cleaner code. Long, complicated functions are hard to test. Simple tests and clear descriptions will naturally lead to shorter, more readable application code.
You’ll write more meaningful tests. With code already written, it’s easy to write tests that just pass instead of tests that confirm useful functionality. Imagine if your math professor only tested you on things you already knew – that wouldn’t be very useful!

Do you have more reasons? Drop a comment below!

This is part of a 6-part series on clean code. It’s some of the most valuable reading I’ve ever done as a developer.