A style guide is opinionated, on purpose.
While many people perceive the act of writing code as logical and un-biased, any developer who has seen their share of spaghetti understands first hand that code is mostly written by humans - and humans are deeply opinionated. For those coming to TouchDesigner from other text based languages, you're probably familiar the idea of a Style Guide. In other languages these often provide anchoring ideas about the best practice for a particular project or how an organization writes its code. Many are familiar with conventions found in the Google Style Guides or in PEP 8 - this resource makes no assumptions of importance, but does recognize the value of strong anchors for developers when they're writing code or connecting nodes.
Style guides are just that, guides. The suggestions outlined here aren’t hard and fast rules, but form and style conventions from people who have tried lots of different approaches, and made plenty of mistakes of their own. For any standard there are likely to be exceptions, challenges, and issues. Code the way you want to code, but also remember that you’re making something that other programmers are going to return to, pull apart, question, interrogate, curse, praise, and judge. Your act of fixing an idea in an operational structure is both a creative act, as well as a measured and considered one. TouchDesigner networks are challenging to share and collaborate in – they are sprawling, nested, multi-layered collections of signal flows. That is to say that they are already challenging to decode – you don’t have to use this standard, but cultivate and implement one for your own sake, and for the sake of your collaborators.
This project has largely grown out of an internal Style Guide that Matthew started when working at Obscura Digital. The initial pieces from that project aimed to collect the best of the Interactive Development team's ideas and practices and collect them into a record that could be shared with new developers. The hope was that having an internal set of defined practices would standardize the teams approach making it easier to trouble shoot another developer's project, and onboard new hires. It was a great idea, but hard to summon into practice. Between fast moving jobs and a looming acquisition, the timing just didn't work out.
Fast forward a few years, and SudoMagic was suddenly asking itself how to better standardize its internal practices - that created an opportunity to revive the project and to capture some of the ideas that had been developing inside of that team. It also seemed like a great time to invite other organizations to share their standard practices and structures. One of the largest challenges when it comes to working with developers is aligning on approach. Any two devs may never see eye to eye exactly on how to solve a problem, but then can agree on how their code is documented so that someone else can understand (or try) what they were doing. This repo acts as the collection of pages that make-up a static site whose content is a collection of TouchDesigner Style Guides. This currently contains contributions from:
Our hope is that other creative developers find this useful, and are inspired to create their own style guides and documentation for their teams.
If you'd like to participate you can start by joining the discussion on github. From there we can walk you through what contributing looks like, and getting you onboard. As a general observation, it's great to come to this process with some established ideas about how you currently structure your projects and why. Style guides often work best when you have an defined opinion and perspective about how you want to work with others. That's not to say that a style can't change - all style guides are living document that change over time - but it is valuable to have a defined idea you can stand behind.