Commenting your Reascript – adamtcroft.com

Imagine this scenario (you’ve probably been in it before):

You’ve written 80% of a song. It has a great vibe, you’re totally in the flow of things and it’s awesome. But it’s 3am and you have to work in the morning (or there’s some other way that real life happens) and you have to stop.

You all know the dilemma – you stop, you lose the vibe, and if you get back to the song tomorrow it just won’t be the same. Most likely you’ll get back to it in a week (hey, you’re a musician – the opposite sex finds you attractive and you have to go out, right?!). By the time you get back to it, the magic is gone and you have no clue what you were doing and how to pick up where you left off.

I know this sounds crazy, but this happens in programming too (okay, well maybe not the going out part – but Netflix man! c’mon!).

This is why you need to comment your code. Today I’m going to take the work out of your hands and show you exactly how to use comments and use them well.

Comments? What are those?

Again today we’ll be covering this topic as it pertains to the language Lua. Comments exist in every programming language, but I’m only going to show you the hows and why’s of Lua.

In short, comments are a way to describe what in the world is going on in your code. Do you take notes on a riff or a mix? Same thing.

In programming, there are two types of comments: Single Line and Multi-Line. This should be fairly straightforward. Here’s two examples.

To write a single line comment in Lua, you put two dashes before your text. See below:

-- Print "Hello, World!" to the console
reaper.ShowConsoleMsg("Hello, World!")

To write a multi-line comment in Lua, you put two dashes followed by two open brackets. At the end of your comment you put two closing brackets. See below:

--[[ Print two "Hello, World!" lines to the console,
with the 2nd "Hello, World!" on a new line.]]
reaper.ShowConsoleMsg("Hello, World!")
reaper.ShowConsoleMsg("\n")
reaper.ShowConsoleMsg("Hello, World!")

It’s really that simple. Therefore, you have no excuses not to use them!

Where do you put comments?

My answer to this question is pretty straightforward: I comment everything.

Some people find this idea downright insane. But I’ve come back to code too often knowing the general idea of what I’m looking at, but not specifically what it does. So here are some proper rules I follow.

Write a comment at the top of your code, explaining what the program is and what it does. Put your name up top if you feel like it. Such as:
```
--[[ "Hello World.lua"
Writes "Hello, World" to the console twice.  Like a boss.
by Adam T. Croft - 2017]]
```
Write a comment after the definition of each function you create. I know I haven’t told you what functions are yet, but just roll with me on this. Like:
```
function printHelloWorld(hello_world_variable)
-- This function prints "Hello, World!"
reaper.ShowConsoleMsg(hello_world_variable)
return
end
```

Write a comment before each new chunk of code that performs an operation. Such as when you call a function or a loop. Such as:

--[[ Store a variable that contains the string "Hello, World!"
then print it.]]
hello_world_variable = "Hello, World!"
printHelloWorld(hello_world_variable)

Between those 3 rules, enough should be commented in your code that you pretty much always know what you’re coming back to. If your code gets extremely complicated or confusing I tend to believe that more comments tends to always be better than less.

Alright, further on we’re going to break into actually writing scripts that serve a functional purpose in Reaper. I appreciate you following along while we get through the less immediately exciting stuff!