Best practices - organization of components, definitions, and files?

Replies to This Discussion

Permalink Reply by WT4 on May 10, 2016 at 8:33pm

Once I am confident that the script works, I start grouping components into clusters.

Permalink Reply by Nik Willmore on May 10, 2016 at 10:47pm

"Stack and group."

Stacking components on top of each other allows named groups to be nice boxes instead of long horizontal ribbons. Then set wires between groups to faint wires so you can appreciate the groups and see the names you assign to them. Happily selecting a component solidifies the faint wires  for inspecting connectivity between groups.

Stacking also lets you post screenshots here to ask questions and get better feedback as you use the forum as a notebook of  progress, as long horizontal scripts won't fit in 721 pixel wide images. I'm careful to leave enough vertical space for the profiler timer of slow components to not be covered up by the component below and do my best to help all the wires be followable too.

Periodically reorganizing into nice boxy groups does wonders for clarity of mind during bouts of confusion.

Permalink Reply by Andrew Heumann on May 11, 2016 at 6:56am

While I appreciate Nik's grouping and labeling, I have to disagree in general - that definition looks to me like a nightmare to work with and debug. Here are some best practices I have relied on and disseminated at the firms I've worked at:

1. Always write your scripts as though someone else is going to have to use and debug them without any instruction from you. This is kind of an overall governing principle that drives a lot of the other best practices.
2. Structure your definitions left to right. This way it is clear what is dependent on what, what executes in what order, and makes it easy to use the "Moses" tool (alt-click and drag on the canvas to spread components apart) to insert intermediate functionality to an already-existing definition.
3. For a given functional group (a set of components that does a well-defined thing) keep all the data going in to the group as labeled parameters on the left, and everything going out of the group as labeled parameters on the right. This is the intent of my "Best Practicizer" tool in Metahopper (now a menu item instead of a component). In essence, you're treating each group as though it's about to be clustered - you've defined what it does, what its inputs are, and what its outputs are. This makes troubleshooting much easier - if something is going wrong, you can easily isolate which group is causing the trouble by looking at inputs and outputs.
   3b. If you're grabbing some value or data (e.g. "STEP COUNT") many times from elsewhere in the definition, don't make a bunch of long wires that connect all the way back to the original source - grab that data into ONE labeled parameter and then connect all your inputs that need it to that - makes for one long wire instead of 20.
4. Annotate, annotate, annotate. Label your params (and if you're in icon mode, switch them manually to text). Label your groups. Use scribbles to mark larger regions of functionality. Use panels for "instructions" wherever it might not be clear how someone is supposed to use your tools. 
5. Avoid "wireless" (Hidden Wires) connections. If you MUST use them, make sure you create params at both ends with matching names so it's clear what the data represents and where it comes from. 
6. Cluster where possible. It's extremely helpful to isolate functional groups into clusters - it makes debugging faster and easier, since you don't have to wait for the whole definition to recompute when making small edits to the inside of a cluster, and it sets you up well to create code that can be re-used later on. However, don't take whole definitions and cluster them. As a rule of thumb, if a cluster has more than ~10 inputs, it should probably be broken into multiple clusters. There is a slight performance impact when clustering, because unlike an un-clustered group of components, which only executes the parts of the definition where something has changed, any time ANY input to a cluster changes, the WHOLE cluster re-computes. Because of this, a cluster shouldn't generally wrap any groups of components that are not related / don't connect with each other.
   
7. Color code your groups. Many firms develop a standard around group coloring so that it's easy to understand what parts of a definition are doing what kind of task. For instance, at Woods Bagot where I work, we have different colors for component groups that highlight inputs, outputs, rhino references, baking, and visualization. You may find that a different set is useful to you, but having a consistent standard can improve legibility. That's my 2c. At the end of the day, everyone works a little bit differently, and that's unavoidable (and not even a bad thing!) As long as you keep #1 in mind, all the rest will follow. 

Permalink Reply by Anders Holden Deleuran on May 11, 2016 at 7:52am

You dropped your mic Andrew..