A Comprehensive Guide to Grasshopper Scripting Best Practices

Some time ago, I wrote a guide to effective script organization in grasshopper to share strategies for structuring Grasshopper scripts. After implementing these strategies myself and receiving feedback from other designers over the past few years, I am now formalizing them into a set of best practices.

This guide is not set in stone and these set of best practices will evolve as the industry and the program changes too. The intention behind this guide is to serve as a written reference that people can use to discuss script quality. The idea is to establish conventions that help make scripts more readable, maintainable and scalable.

The world of software development has been doing this for a long time now. Most software companies have coding standards that prescribe how to format and author code for better readability and maintainability .By drawing parallels those principles, we can learn from them by setting our own scripting best practices.

Clean script anatomy

To make sure we are on the same page, let's define some terms around Grasshopper scripts.

The Canvas

The canvas is the workspace where components are placed and connected.

Components

Components are the building blocks of Grasshopper scripts, executing specific functions. While many are native to Grasshopper, additional components can be added through plugins.

Operations

Think of operations as cohesive units within the script. They are a group of components that execute a specific task relating back to the model.

The Best Practices

Understanding the anatomy of a script is important because this entire guide is focus on the readability of scripts. It follows the Newspaper metaphor taken from the Clean Code book by Robert C. Martin which is considered the "bible" of code formatting in software development.

The metaphor follows something like this :

Your code should read like a newspaper. At the top you expect a headline that will tell you what the story is about and allows you to decide whether it is something you want to read. The first paragraph gives you a synopsis of the whole story, hiding all the details while giving you the broad-brush concepts. As you continue downward, the details increase until you have all the dates, names, quotes, claims, and other minutia.

Taking this metaphor and as we will see soon, the operation colours are our headlines. The scribbles in our operations will be our paragraphs and the components and it's containers within each operation will be the details of our "story".

But for us to turn our scripts into "newspaper articles", we have to start with our components and work our way to operations.

Name and use Containers

Scripts can become cryptic labyrinths. Most often, you will find yourself panning left and right, trying to desperately remember the data you are working with.

Naming containers will help eliminate that confusion. Instead of following wires around, you can label containers as a reminder of what you are working with. It provides context to your operations without having to remember what you are working with.

It's very disorienting to keep panning left and right to remember what data you are working with. Containers provide the much needed context for our operations.

Use different wire styles

Using only the default wire-style will lead to a lot of visual clutter.

Different wire styles be used to hide wires that you don't need to see at a given time. This normally means wires between operations don't have to be seen all the time. Given the use of containers, we don't need to see wires to tell us what we are working with. When we do make use of different wire-styles, we get a more organised and readable script.

The theme is that we only want to see wires based on the level of detail we are working with. That means we should keep wires in operations but wires between operations don't have to seen all the time.

As a starting principle, I would use the "default" wire style between components in an operation. The "hidden" wire style between operations and the "faint" wire style for components that I want to see the flow but I don't need it to be obvious.

To actually do this in Grasshopper, you can right-click on any input/output of a component and select the relevant wire style.

Use scribbles to explain operations

By using different wire styles and named containers, we can start to better see our operations of our script. The next step is to write our "paragraph headings" by using scribbles to explain our operations.

You can bring a scribble component onto your canvas pretty quickly by using the search bar. All you have to do, is type "~" then followed by your text.

Scribbles provide a high-level overview of what your script is doing without drilling too far into the details.

Colour groups to classify operations

With that, the final step is write our "headline" by colouring our operations. Colours will help classify our operations, letting the reader know what type of operations are present in the script.

It let's us highlight important areas of the script like inputs or outputs but more importantly, it also gives our reader a sense of what's going on in the script.

The coloured groups and the scribbles make the script very readable. If the reader then decides to dive deeper, they can zoom in on the components or operations while understanding the high-level steps of the script.

You can take this a step further by setting a consistent colour legend for all your scripts. I do this for all of my scripts. I do this to build an association of a colour to an operation type.

To do this systematically, I use this metahopper workflow to auto-colour the groups

A Note on Script Size

This guide doesn't touch on how big scripts should be but it's actually an important factor in software development. The concept is that you don't want your reader to be wading through a sea of components/code.

But based on my experience and discussions with others, I can't find a commonly accepted metric for how big scripts should be. My thoughts around this are still developing but my thoughts keep bringing me back to "mental squeeze points".

As in the time to break up a script into smaller scripts is when you find yourself lost and overwhelmed by all the functions the script is doing. I find that a good instinct to break the script up into smaller scripts. It's the idea of unloading those functions to another script, giving you better cognitive space.

Final Thoughts

Script organization is a topic that has been heavily discussed in the computational design community. It can be a controversial topic, there are people that don't believe in script cleanliness. Their argument revolves around the fact that it takes too much time to keep a script clean. That it's better to complete the work and move on.

While I think there is a place for speed, if your script needs to be reused later, it's going to take a lot more time to understand it. Any script that needs to be distributed to others or reused needs to be clean and readable.

Much like programming, developing Grasshopper scripts is a lonely task. A lot of times, we don't think about others reading or using our work, so we aren't used to cleaning up after ourselves. We need to change that if we want to work in teams that use Grasshopper scripts for work. Much like the software industry, we need a set of guides to help us work together.

My hope is that this guide is the start of that movement. It's a reference that I can share with others to come to an understanding of what scripting standards should be.