Personal tools
You are here: Home documentation Style Guide PrimordialStyleGuide
Views

Realms of Style

Dollar arguments, Abstractions, Subpatches, Inlets/Outlets, Trigger, Visual Layout, Patch organization, Filesystem organization, Send/Receive/Value/Table naming conventions, Abstraction/Subpatch naming conventions, interfacing (e.g. APIs? and inter-patch communication), general "Programming Recommendations" (e.g. counters, initialization, negation, and other everyday stuff)

Naming

Frank Barknecht:

I use the underscore style sometimes but often a simple "dash" style: "r some-thing" instead of camelCase. My reason: It doesn't need any Shift-key-combinations on German keyboards, and I find camelCase hard to read. I always seperate $0 with a $0-dash. $0myGod is easy to misunderstand.

Enrique Erne:

$1. or $1- or $1_ (which separator?)

Chris McCormick?:

In general though I find using '/' as a divider more satisfying than '.' or '-' or '_' because it is more consistent with the OSC way and with the whole libdir thing, although maybe that's more confusing than clear. Hmmm. I used to use '-', hence the names of s-abstractions.

Luke Iannini:

There are two kinds of separators: those separating a hierarchy and those acting as a space. I vote for "-" as equivalent to "space", since it seems to be the most common. Then, for the hierarchical separator, I think we should either always use "/", or reserve "/" for OSC addresses and use "." when making a "Pure.data.hierarchy".

One extra point there is that separating $0 or $1 etc. should be done with the hierarchical separator rather than the spacing separator.

Globals

Frank Barknecht:

I tend to use ALL_UPPERCASE for globals.

Send/Receive pairs

Frank Barknecht:

When I want to name matching send/receive pairs I use $0-some-s and $0-some-r.

Luke Iannini:

I like Frank's suggestion to suffix both the send and receive of a pair, since it lets one know that when you see a "-s", there's a matching "-r" and vice versa. The only time I think I do this is when using GUI objects, so, for me, this also helps to identify a send/receive as belonging to a GUI object.

Arguments

Frank Barknecht:

Yeah, numeric ordering is fine, but putting $0 first means, that using $1 inside the abstraction is $0 from the parent, $2 inside the abstraction is the value called $1, $3 = $2 and so on. Putting $0 last lets you have $1 = $1, $2 = $2 and so on in abstraction trees/hierarchies like above.

Enrique Erne:

now a bit personal: i don't like $0 :) . It's fine for a namespace within a patch, but I found myself often needing to access something from "outside" so i have to pass $0 around, which is ugly. I much more prefer a global receiver and route everything. so i pass the name of my patch to it's abstractions. abstracions get global receiver with $1 in it which is the motherpatchname. it helps for orientation i.e. look at the window title:

yourabstraction.pd (mother) isn't it better than: yourabstraction.pd (1284)

you can even use it for [sssad $1/vol]? without having the $0 making your sssad key into a unusable name. If I have GUI inside the GOP each sliders send and receive name begin with $1. or $1- or $1_ (guideline please!), that makes it possible to hijack the patch from an other patch. Like the midilearn or automator patch can control any slider in this setup.

Abstractions

Matt Barber:

There's one style of patching which suggests that abstractions should operate as closely as possible to built-in objects, which (in vanilla at least) are usually also basically unaware of their surroundings

GUI elements

Enrique Erne:

For GUI elements like sliders I've never regret to use a kind of name hierarchy ($1.vol), usually mypatch-myabs-myparameter or mypatch.myabs.myparameter or mypatch_myabs_myparameter or whatever. so you can hijack your channel aux-sender with anything.

but that means you can't open a patch multiple times, no problem for me because i reuse code always with abstractions.

Audio Channels (throw~/catch~, s~/r~)

Matt Barber:

Stereo should not stand out as a preferred case... many other more general nomenclatures could apply, e.g. ch1 ch2 ch3 ch4 (or ch0 ch1, etc. for channel array lovers), or just the numbers, or something else. This might allow code from a stereo garden to be plucked and implemented in a multichannel space in the future, with little worry. Also, actual pairing of loudspeaker to channel number should not, in general, be codified. There are too many "standard" and acceptable configurations by now to anoint some over others.

Debugging

Matt Barber:

decouple number boxes and bangs used for debugging from the workings of the patch

Abstractions

Matt Barber:

Also, I forgot to mention that I think abstractions (and maybe to a lesser extent subpatches) should follow the right-to-left conventions of Pd objects for input/output, even if it complicates layout on the parent. So for instance [gate]? from cyclone is bad Pd style, IMO, and an abstraction designed to mimic it ([gator]?, say) should be set up more like a multi-outlet [spigot]?. Even [timer]? still bothers me, but I guess it's a special case.

Abstraction/Subpatch Naming Conventions

Matt Barber:

Abstractions, whenever possible I think, should try not to conflict with names in extended, even when the patch is designed for vanilla. Also, I think it's helpful to include tilde in abstraction names when audio signals are involved.

Programming Recommendations

Matt Barber, Enrique Erne:

Always use trigger for one-to-many connections

Luke Iannini:

To invert a toggle, use [== 0]?. Use the loadbang of the parent of both abstractions to initialize two or more interdependent abstractions.

Dynamic Patching

IOhannes? M. Zmoelnig:

someone might change the way Pd builds a patch from a file. or change the fileformat.

being inofficial/unsupported doesn't meant that it does not work. it means that it is your (the user's) fault if it stops working in future versions.

Visual Layout

Marius Schebella:

I am quite pedantic in regard to spacing and aligning of objects. I started to space all objects using ctrl+arrow keys. that way all objects are spaced like on a grid and always a multiple of 10px away of each other. I don't know if that should go into a style guide, but for "official" patches like tutorials it could be considered. It is almost not possible for me to look at the montreal abstractions...

do not store patches with position <0/0. some window managers will not allow to drag the patch window around. (oh, and please don't place objects outside the canvas and esp. not <0/0, having to scroll to the left to see the beginning of a patch can cause heart attack). and not all people have widescreen monitors or hi-res monitors, so I think 1024 should be the maximum width of a patch.

Frank Barknecht:

A lot can be had with at least left-aligning connected objects. You get a clean left side, which is the important side of most Pd objects because of the hot inlet there. Then even if something like the "a"s in your [t b a a a a]? aren't aligned anymore because of platform/version issues, you still have the clear layout of the main logic flow to the left.

It's also good to leave a bit more room to the right of objects and comments to avoid overlapping boxes. I think, Pd-extended runs quite a bit narrower than Pd-vanilla with a 10px font on Linux, which is what I use. (I'm guilty of not leaving enough room to the right myself, though.)

Organization

Marius Schebella:

I also want to point out the importance of good grouping. sometimes I use bg canvases to underline that certain objects belong together (do some transformation or algorithm).

If I work on big patches that run as installations (no interface) the parent patch is basically empty, it only shows piece information and credits, everything is in a subpatch called [MACHINE]?. and that usually is more a visual representation of the space (according to positioning of sensors/speakers) or a basic overview of the patch structure with an short explanation of what the different subpatches are doing.

Matt Barber:

This is a good point. In fact, for some patches e.g. for interactive pieces to be sent to musicians who don't do Pd for a living -- =o) -- I prefer to put everything in a subpatch which has a GOP control surface. I think it's productive to petition against the "spider web" style, but even too many objects and connections on the main patch seems wasteful somehow. It's nice to include a subpatch which can be opened with a bng, that is basically a readme. I do this for abstractions, too, but without the bng -- just something to describe how it works inside the patch itself, I suppose as a quick substitute for a help file.

Documentation

Marius Schebella:

even, if everybody says, pd patches are their own documentation, because everything is visible, that's not true, commenting should be an important part of patching (cyclone's comment allow differnt fonts, sizes, colors and width of comments).

some things are important for patches that should be portable. please mention, which libraries are used, and consider to use declare to load the objects.

Filesystem Organization

Marius Schebella:

then, for patches that rely on abstractions, *maybe* it would be good to give them either unique names or put them into subfolders. (I have to say, I do not really stick with this rule. but at least one thing: the main patch should always be recognizable, I usually put it in capital letters, so that people know, which patch to start.

resources (images, textfiles, data) could be kept in a subfolder, too. (just think of the GEM examples, how often one of the images or videos can not be found. - at least in the past).

Matt Barber:

When 0.39 begins to wane (so [declare]? can be used), it might be productive to keep abstractions in subfolders, and possibly control in one and tilde in another. Same, as you suggest, with textfiles, qlists, images, and soundfiles. This way the main patch is there cleanly for anyone who might need to use the patch besides you, and especially nice for musicians.

For Deliberation

Matt Barber:

if there's an adequate solution with an abstraction, should one use it rather than an external? Does this change in pedagogical situations where a student might profit in learning from a rather sparse set of unit generators? Does this change when performance is required above all?

for GOP abstractions, is it bad form to cover the abstraction name and arguments with a canvas? What if these things are printed as labels on canvases?



Powered by IEM Powered by Plone Section 508 WCAG Valid XHTML Valid CSS Usable in any browser