Writing Code, Building Comment Scaffolds

When approaching less-obvious coding tasks, I really enjoy building scaffolds around the thing I’m working on.

You only zoom out occasionally to see if you’re still on the right track and what’s up next. Then you can tackle the next small, isolated problem at a time.

Less things to keep in mind!

It’s so nice when you only have to keep a small part of what you’re building in mind at a time! You don’t have to worry about everything at once - instead you’re solving one small task after the other.

Unit tests and test driven development help to do this if the system is larger. They are starting simplistic will be expanded in tandem with the actual code.

Before it’s time to write tests though, there’s a simpler thing I start with.

Writing comments while reasoning about the code structure and before writing the actual functionality.

Building a scaffold.

It starts with the name of the function and the signature.

The function has one job to do, so it’s named after the thing it does. The incoming arguments are drafted out and the return value(s) determined.

In case of Go, I insert a dummy return value right away to satisfy the compiler, and get to the next most important task: writing a function comment.

The comment describes the reasoning why this function exists, and what job it does.

Time to go deeper.

Next, we can plan how the function will go about doing the thing it’s supposed to do. What’s going to happen inside?

I like to draft rough steps in the form of simple comments:

// StringSillifier makes strings less serious, for fun
func StringSillifier(seriousString string) string {
    // See if it's a special case which can't be fun
    // Handle multi-word case
    // Handle name case
    // Make even sillier
    // If it's a good one, ping me in slack about it
    // Return the best result
}

I like to think of those, as a scaffold. Divide and conquer is another, more common name, for subdividing a large problem into smaller ones.

Now, instead of having a single big thing to work on, which might have seemed overwhelming, I have multiple small tasks which I can addressed one after the other.

In a first approach, some can be simply mocked or faked to see if everything else still looks solid once that part would be done.

See the big picture before diving into details.

With that comment scaffold in place, I can see whether I have skipped important steps at a glance. Maybe I prefer this approach, as I’m more of a top-down planning person. This approach helps me see parts I would have missed prior to writing things down.

You can also get a feeling for where the complexity will reside and you can re-evaluate whether you’re trying to take on too much in a single function. The earlier you can simplify, and package out functionality in to other well-defined helper functions, the cleaner the code you’ll have to write will be.

Solve one problem at a time.

Once the comment scaffold is in place, we can approach the small problems at our own pace, and don’t have to keep the grand design in mind at all times.

The code will grow next to the scaffold, and those helper comments can evolve together with it. Eventually, only the “why” comments and big-picture annotations will remain. The nitty-gritty implementation descriptions will be replaced by code.

I really like techniques, which help me to gain focus. Writing up designs and structural approaches in the open, where they see the light of day helps a lot with that.

This technique seems easy, but I found that it’s a nice trick not everybody is aware of. Especially not if you’re starting out with coding. I think, it makes the process more enjoyable, less complex and can provide a nice fluent transition between big-picture planning and nitty gritty implementation work.