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

Edit history

Edit: -1 of 1
Time: 2008-08-08 09:57:05
Note: /pd/pd/docs/style-guide/PrimordialStyleGuide/edit "grabbed last bits from discussion thus far"

changed:
-
= 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