This page contains a collection of advice and guidelines for visual programming in Grasshopper that will help you to become a better designer. Most advises are opinionated, but they have proven in practice. Feel free to open an issue and add a line or two; this is a growing list.

The first section gives advice that always apply, even for short scripts, and the next section talks about guidelines for scripts that fulfill essential tasks in a project.

Always, …

… save before you start to script.

In Grasshopper, automatic file backups are only created for documents that have been saved before.

… be structured.

Language is an expression of thought. Writing an algorithm is nothing else. Keep your thoughts organized, subdivide them into chapters, use hierarchy and make them readable.

… take your time (long-term).

Learning (visual) programming is like learning a language or an instrument: it is not done in a day; it takes time and effort and one can only get better with practice. If you start simple and do the advanced stuff later, learning can be fun. While getting more experienced, improve your workflow: Use shortcuts, get to know Grasshopper components by their icon only and learn from others.

… take your time (short-term).

Writing complex algorithms cannot be done in a rush; there is also playful tinkering, trial, error, and luck in the mix. Also, your mind needs to breath: if you are stuck on a problem, take a break, enjoy a cup of coffee or go for a walk. The best solution often arises, when we are not constantly sitting in front of our problem.

… keep in mind that there is more than one solution.

Programming lets you do almost anything; we can assume that the solution must be out there, somewhere, we just need to find it. This search can be tough and sometimes we miss the forest for the trees. But often, there is more than one solution, more than one approach to achieve something. We might need to take a step back to go ahead and to explore another route, to find an alternative solution. But it’s these detours and dead ends that let us grow and become better designers.

… annotate.

Commenting in Grasshopper is a horror, yes, but you shouldn’t run away. Use the Canvas search and hit ~ to add a keyword. You can use this to add context to containers, sliders, or other objects in your algorithms.

… visually separate suboperations.

Often, we need several small operations to perform some logic with our main objects. Setting these minor operations aside from our main stream of action helps to visually trace the most important transformations of our algorithm. On the other hand, if two equally important streams meet, they should both deflect. Yet the connected wires and their grips should always be traceable. All in all, we need to find a balance which offers the best readability.

… group.

Besides setting minor operations apart from the main stream, we can group components that belong to a particular task. Select them and press Ctrl + G to group them in your default color and add a little description. Much better.

… avoid to set internal data on components.

Grasshopper allows us to set values and reference objects directly in the context menu of an input grip. But don’t do it; never ever. Doing so makes reading the algorithm much harder and debugging becomes a nightmare. Instead, use either panels to set values or containers to reference geometry from Rhino. If nothing is attached, we can then safely assume that the default values are used. For Boolean values: True can also be written as 1 and False as 0.

… know how data trees work.

If your algorithm is misbehaving, it’s probably due to mismatching data structures that. Learn how data trees work.

… Math will be your friend.

Yes, you can trust math. For most geometry problems, there is already a good solution. Put your scripting away and think about the shapes, their relation to each other and of possible transformations in space. What needs to go where? Which properties relate to the current shape? Which mathematical term should I look up? Wasn’t there something in the vector section about this?

When serious, …

… keep dependencies low.

Two types of dependencies exist in Grasshopper: geometric objects from Rhino and external plugins for Grasshopper. Both should be kept to a minimum. Especially, when working on a project with several people and over a longer period of time.

Referencing geometric objects from Rhino with a Grasshopper container is convenient at first, but it requires that the Rhino file is always opened in parallel. Also, the referenced geometry must not be deleted in Rhino; otherwise the connection is lost. The problem is that there is no hint in Rhino that an object is needed by an algorithm. To bypass the problem, at least for simple shapes, it’s possible to right-click the container in Grasshopper and select Internalise data. Now the object is saved within the Grasshopper file. If this is not an option, the referenced geometry should be on an extra layer, have another color or the filename should indicate the dependency.

Other dependencies are components that are made available by external plugins for Grasshopper. Using one of them also requires all persons to have the same plugin installed when they’re opening the file. Also be aware that there are rare cases in which plugins are not backwards compatible.

Before using a dependency, you should question yourself, if a plugin offers a unique feature and if it justifies the extra load. If a component from a plugin is used, because it offers a shortcut to replace two or three built-in components, then it’s better to use what’s already available. Also, there are plugins that offer similar features, for example to work with meshes. Here, stick with the components from one plugin and try not to mix them.

… use version control (kinda).

Version control should allow us to go back to previous versions of an algorithm and to keep track of changes between the instances. Unfortunately, Grasshopper lacks proper built-in version control. Yes, documents can be saved as backup and revision comments can be added in the document properties, but this is far from what Git or other version control systems offers for textual programming.

For Grasshopper, there is no tool that offers a convenient way to track changes and to revert to previous instances. To achieve a basic implementation, each team has to develop their own methods that suit their workflow best. Have a look at the how-to versioningto get some inspiration. But it’s also more of a log and there is no capability to compare differences between two versions.

… separate input parameters, programming and results.

Every script turns some input parameters into some kind of output. When the programming is done, we can reuse the script to produce different results based on the same principles; the script becomes a tool. And because the script can be used as a tool, not every user needs to understand how the algorithm works internally. Help users of your script to identify the parameters that can be changed and where and how to get the results.

It’s always good to write your algorithms in a way that it can be understood by others and your future self. This goes hand in hand with proper documentation. While documentation is geared towards other programmers, this advice pays attention to the experience a user will have when interacting with your code.

Input

stuff is going on

Output

… implement proper documentation.

If you just read the previous advice, you know that documentation is important. And, because it’s so important, let’s not mind the repetition here: Write your algorithms in a way that it can be understood by others and your future self.

Several of the advices above gear towards some kind of documentation and they all add up to a proper documentation. Continue to read about the Grasshopper elements that can be used for documentation. However, the main takeaway here is that a holistic documentation is more than a collection of elements; proper documentation is part of a bigger strategy. Whether you work alone or in a team, you should think about how to make your thoughts and files future proof. For example, give each file a written introduction about the purpose of the file, its dependencies and schematic layout. Write down your workflow somewhere and state there, how all your scripts interact with each other. Think how others can understand you work and your workflow without further questions.

… a rough documentation is better than an incomplete one

Although there are the script-as-a-tool-idea and the advice to thoroughly document your programming (as described above), some scripts grow from project to project and they will include dead ends, solutions for corner cases, and unfinished work in progress. A good idea is to visually separate the core parts of a script from the added bloat. However, this can backfire and often some code on the side becomes a new key feature. Now the layout of the file and the documentation should be rewritten, but for some reason updating a documentation is far more often missed than writing the initial documentation.

Now, the following advice undermines the previous ones a bit, but it’s better to have a bumpy documentation than a proper one which isn’t up to date or doesn’t cover everything. You should annotate your code as you go and comment why there are some components on the side and what problem they try to solve. If you have to unexpectedly interrupt your work on an algorithm, anybody should be able to continue as effortless as possible.

… use breakpoints.

Some scripts in Grasshopper take forever to execute and they are no fun to open. Besides, you never know if something useful is computed or if there is a component in data structure hell. If your script takes more than a couple of seconds to load, you should use breakpoints. In Grasshopper, this can be achieved by disabling a component in the stream, using Data Dams, Stream Filters or Stream Gates. You can also split the algorithm into smaller parts that can be executed individually.

This also adds to a greater goal: Make your algorithms fun to use. Some files are frustrating to use and even though they may host some ingenious solutions, their lack of usability kicks them into nirvana.

… know that things break.

Unfortunately, they do. This reminder is not about data loss and securing your files regularly but about dependencies in software and programming. Your algorithms are the source code to generate your output. It seems obvious to not worry about the output too much because it can always be recreated. However, your algorithm was written with a certain version of a software and some external plugins may not compute with the latest version. It can be quite cumbersome to reproduce a certain software environment, especially if this is related to a specific version of an operating software.

To cut this short, you should also save the output files of your algorithms, for example geometric objects as DXF or STEP files. Also, save the parameter settings that lead to a desired output. Even just a few sliders can produce a huge amount of possible results which makes it hard to reproduce a specific instance.