-
The SuperCollder IDE automatically indents code as you work. You can rely on this to format things pretty reasonably for you. There are a few things it gets wrong, or that are not to my preference (and maybe things that are not to your preferences as well) - but I find that consistancy is more important than style specifics, and it’s not always worth the mental overhead to try to format things yourself.
-
You don’t have to use Git to organize your work, but it really does help once you’re getting to middle-sized projects or pieces of code.
- There are a million Git tutorials if you want to learn the basics. The GitHub application is super easy to use. Spend three hours on one of these quarantine days with tutorials and trying out the basics of committing and branching (feel free to skip more advanced things), and you’ll know enough to be very useful.
- I organize my projects into separate folders, even if they’re just a single file to start. Each one is a git repo.
- I try to commit changes once per work session, with a descriptive message to let me know where I left things (e.g. “Drums sounding better, added reverb and compression”). Every time I work, I try to jam a little and record it (this helps me keep myself from going too heavy on code - music is the goal!) - I’ll name these recordings with the git commit hash, so if I listen to it again in 6 months and it sounds great I can easily roll my code back to that state.
-
SuperCollider lends itself to MANY different coding styles - that’s one of it’s biggest benefits, and biggest hazards.
-
It’s probably most important to write things in a way that you can make sense of (or, more specifically, you-two-months-from-now - when you re-open that project and are wondering “wtf was I even doing here”). Most people are not writing SC code to be shared, so really it’s communication with yourself, about your musical ideas.
-
It helps a lot to spend a little time mapping out your signal chain or musical processes, and then naming and organizing your sc code to match. I usually try to go back and do this after I’ve had a more free-form/playful experimentation session that feels promising (I rarely do it up front, before writing code). Variable names, ordering, etc., should match the way you think about what you’re creating. Use comments to clarify things and take notes as you go - it will help you navigate later and remember weird details (of which there are mannnnny).
-
Code isn’t clean and organized up-front - it becomes clean an organized by revisiting it again and again, improving things gradually over time. The technical term for this is refactoring - being able to refactor your code without breaking it is probably the most essential coding skill you can have.
This labor can fit into a creative practice very naturally. You simply can’t always have intense and productive day-long studio sessions - sometimes, you only have an hour to work and you’re a little tired, etc. These are great opportunities to pour a glass of wine and do clean-up tasks on code - add comments, clarify variable names, re-organize. Then you commit to git so if you screwed something up, you can go back to the old version
-
Read other people’s code and steal their ideas.
-
-
This isn’t done much but - consider asking for code reviews on this forum. It can be super helpful to have people more deeply familiar with SC (or any programming language, for that matter) look over your code and offer suggestions and comments. It can take time - be laborious even - so don’t expect a million responses, but it might yield some good information!
Related to this (and to use auto-indentation in the most effective way):
Be consistent about opening and closing brackets.
If you open a bracket on one line – and opened only that one bracket on the line – then the closing bracket should be on a line by itself. Don’t close extra brackets on the same line.
// yes
array.do { |item| // opened a brace
item.someMethod( // opened a paren
arg1,
arg2,
arg3
) // close ONLY the paren here
}; // close ONLY the brace here
// no
array.do { |item| // opened a brace
item.someMethod( // opened a paren
arg1,
arg2,
arg3
// huh??? looks like nothing on this level. confusing
) };
If you open multiple levels of brackets on one line, close the same levels on a line by themselves.
// yes
Pseq([ // both paren and bracket opened here
a, b, c,
d, e, f,
g
], inf) // both bracket and paren closed here
// no
Pseq([
a, b, c,
d, e, f,
g
],
inf)
// yes
Pseq(
[
a, b, c,
d, e, f,
g
],
inf
)
// OK for indentation, but a little confusing
// (too easy to lose the inf argument)
Pseq(
[
a, b, c,
d, e, f,
g
], inf
)
It takes a while to get used to this, but it’s worth the effort. Code with essentially random formatting is much harder to read. When you go back to code that you wrote a few years ago, readability makes a big difference.
On the same note – when I started coding, I thought it “looked cooler” to have short variable names. Over time, I’ve come to feel that longer, descriptive variable names are better. If, for instance, I’m allocating a bus from which to record a signal, in the past I would have called it recBus or even rec, but in the last few years, I’ll tend to write out recordBus. You don’t have to be obsessive – busForRecordingExternalSignal is ridiculous – but the time and keystrokes you save by shortening variable names will cost you time later when you’re trying to figure out what you meant.
hjh
As an alternative to using git to keep track of versions you can use a function like the one below. It will save a copy of the currently opened documents in the IDE and record whatever is playing into a timestamped folder. This way you can save different versions of the code and the resulting sounds so you can revisit at a later time.
(
~saveWorkspace = {arg name = "wip", folder = "/path/to/root/folder", rec = true;
var workspace = "%/%-%-%/%%".format(name,
Date.getDate.year, Date.getDate.month, Date.getDate.day, Date.getDate.hour, Date.getDate.minute);
var current_doc = Document.current;
var current_path = folder.standardizePath ++ "/" ++ workspace;
var dirname;
if (File.exists(current_path).not) {
File.mkdir(current_path);
};
Document.openDocuments.do({arg doc;
var file_name = PathName(doc.title);
var path = current_path ++ "/" ++ file_name.fileName;
var content = doc.string;
var file = File(path, "w");
path.debug("writing...");
file.write(content);
file.close();
});
if (rec) {
Server.default.record(current_path ++ "/SC_" ++ Date.getDate.stamp ++ ".aiff");
}
}
)
there is no such thing as a “git account”. you can still use git without using github or gitlab.
true. i edited my comment for clarity
I want to contribute from a total beginners/non-programmers point of view.
Having looked over some code, a common style of writing becomes perceptible yet I wonder if there are conventions (something like a basic grammar everyone learns). For example: The way comments are used: Why not putting comments below a line of code? Instead everyone puts it over the respective line. While this isn’t a particularly strong example yet some convention shines through. Can I just grab any book on coding and apply the writing conventions found to other languages or is this different for every language? Is there a good (brief) introduction into those coding habits?
I remember having a lot of these sorts of questions when I started programming - and I’m still not sure I have a straightforward answer!
When you’re contributing to a larger project, you would usually follow the stylistic patterns of that project, including things like comment style and verbosity, variable naming (short? long? hungarian? etc), etc. O
f course, for your own projects - as I said above - your real only commitment is to yourself, and specifically to yourself in the future, when you need to revisit a piece of code. So, you owe it to yourself to be consistent and careful about these style details, but you’re also not beholden to any guide or best practices other than what helps you. I’ve changed style details on my personal music projects many time over the years - never drastically, but mostly in subtle ways, as I found something that worked better or no longer worked for me.
As far as learning better practices:
-
Take some time to browse SuperCollider projects on GitHub - keep an eye out for code that strikes you as highly legible, clear, and aesthetically sharp and try to note details like formatting, variable naming, comments, and overall organization.
-
Often large projects or languages will have an associated style guide - these probably reflect learnings of many developers over many years, so they can be a good place to pick up details. Some languages are closer to sclang than others, so depending on the language (or the project), a style guide may apply more or less. Take a look at style guides for languages like dart, go, swift, typescript, or even C++ - and feel free to ignore parts that don’t seem like they apply to sclang.
-
Iterate! Usually, when I revisit some code after a few months or years, I’ll go through it step-by-step to understand what it’s doing - part of this is cleaning up things like comments, variable names, organization. If every time you revisit code you fix things that weren’t clear, you’ll very quickly end up with a lot of code you can open and start working with immediately, without undue head-scratching or WTF moments.
-
Wendy Hui Kyong Chun points out that source code “only becomes source after the fact” - when you execute some code, that code is only a very tiny part of the overall behavior that occurs (SuperCollider is a complex beast!).
With that in mind, I sometimes find it helpful to think about source code as a way of describing and documenting what is GOING to happen (rather than a machinery that makes it happen). When working with SuperCollider, you’ll execute a million variations of your code a million times, and ONE of those times will sound the way you want it to: at that point, you really want your code to be source code - code that describes what just happened in order to make that awesome sound.
Finally - I googled around a little - here are a couple links to articles / guides that cover the basic of writing clean code, if you’re looking for reading material:
I remember a nice collection of conventions on the mailing list, but can’t find it in the archives …
But have a look at this: