TableSmith Tuesdays – Part 3: The Importance of #Comments

Posted on Updated on

Let’s talk about something that is of vital importance if you are someone like me: I get started on a Project, get deep into it, and then leave it dead for months if not years. Recently while doing some things for work, I was in need of a Flashdrive. So I pulled it out and went through it to see if there was anything important on it. I did! I found two unfinished Tablesmith tables, I couldn’t believe it. These were being developed in ’07! So I threw it in the table folder structure and fired it up, sadly to say they were incomplete. I unfortunately was too excited about my discovery that I sent a note to the Yahoo! Group saying I had found these tables. When I was pestered to share I was embarrassed that I had not completed the tables. So I began to find out what wasn’t done.

Upon first investigation every referenced table had some sort of data but wasn’t being displayed. So I slapped the [Reference] on to the tables and what happened? I crashed TS! This couldn’t be a good sign. After some debugging I got it to work. But then I ended up not knowing what I was trying to accomplish.

Here’s What I had:

:Activities
1,[Meetings]
1,[Performance=%iTypeOfCollege%]
1,[Educational Activities]
1,[Activities=%iTypeOfStudy%]
1,[Activities=6]

;Meetings
1,Roundtable Discussions
1,%sRankTwo% Meeting
1,%sRankThree% Meeting
1,%sRankFour% Meeting
1,%sRankFive% Meeting
1,%sRankSix% Meeting
1,General Members Meeting

;!Research Activities
1, Magical Research into:
1, Historical Research into:
1, [Timing] [Educational Activities]

#Performance Education
#Theoretical Education
;Education Activities
1, [Timing] %sRankThree% Lecture
1, [Educational Activities]
1, Graduation

#Performance Composition
#Theoretical Composition
;!Composition Activities
1, [Timing] %sRankThree% Performance
1, {if~%iOrganizationType% = 1 ? Graduation Performance / [General Activities]}
1, [Educational Activities]

;!Performance Activities
1, [Timing] %sRankThree% Performance
1, Galas

;!Social Activities
1, [Timing] Dinner
1, Roundtable Meetings

;!General Activities
1,[Timing] General Membership Meeting
1,[Timing] %sRankThree% Meeting

;!Rare Activities
1,Ritual Suicides!!

;!Social Activities
1, Dances
1, Charity Fund Raisers
1, Potluck Dinner

;Educational Activities
1,[Lectures].
# [symposium]. [Research Projects].

UGH! How could I do this to myself? It’s so frustrating to come back to a table in this condition, and let’s not even mention the guy who didn’t write this table, that has an awesome idea that the creator didn’t have and wants to quickly add it.

Fortunately for myself, I tend to write my tables in sections. This so happens to be the Activities Section (creative, right?) By breaking the table into smaller sections we could treat it almost as if it was its own table. So let’s start with the Activities Table:

:Activities
1,[Meetings]
1,[Performance=%iTypeOfCollege%]
1,[Educational Activities]
1,[Activities=%iTypeOfStudy%]
1,[Activities=6]

First things first we need to define that this is a separate section of the table. And then we can move on.

#------------------ [Activities Subsection] -------------------

Moving on from there, let’s take a look at this table a little more in-depth. [Meetings] calls a Meeting Table, great. Pretty self-explanatory, and no need to add any comments. As we can see from the code above it does use some variables.

Let’s talk a little about the way that I use my variables (at least in this table, and in the way that I mean to use variables.) each variable has, or should have a letter in front of it: i or s. i means that it is going to be an integer (A number). s stands for string, which is going to be your text. Back to that table.

The [Meetings] table works because I am using string variables that I set at the very beginning of the table. And, because of the way I am very descriptive with my variables I know that RankOne is the first rank of these guild members.

[Performance=%iTypeOfCollege%] Seems to be trying to do a performance based on the Integer Number of the TypeOfCollege. Ok, well in a table that already spans almost 400 lines, scrolling up and finding the variable assignment can be difficult. So because I am lazy what I should’ve done would’ve been this:

#------------------ [Activities Subsection] -------------------
#;Type of Study
#1, |sTypeOfStudy=Research| |iTypeOfStudy=1|
#2, |sTypeOfStudy=Education| |iTypeOfStudy=2|
#3, |sTypeOfStudy=Composition| |iTypeOfStudy=3|
#4, |sTypeOfStudy=Performance| |iTypeOfStudy=4|
#5, |sTypeOfStudy=Social Club| |iTypeOfStudy=5|

Excellent! Now with a quick look at the top of the screen I can see that a Research Study is going to be 1, and so forth and so on. At this point I know that I am going to have to keep referring to this comment as I continue to flesh out and finish this section of the of the table. Before we go on, [Performance] is its own subsection. Which actually has been kicked into its own table. A Bard Song.tab

[Educational Activities] is real helpful to me. So see how the table is actually at the end of the original text? That tells me that all those tables in-between are supposed to be doing something. And the following two table entries: [Activities=%iTypeOfStudy%], [Activities=6] are of no use to me in determining what all those groups between [Research Activities] and [Educational Activities] are for! Now I am wishing I had made comments. I’m also to the place that keeps crashing TS! I can tell by not using the “;” relative probability that the entries in that group are supposed to be numbered. And trying to call [Activities=5] is gonna crash TS! Not my smartest moment.

What I should’ve done is make a comment here about what my intention was going to be with these two tables that have no support underneath it.

#------------------ [Activities Subsection] -------------------
#;Type of Study
#1, |sTypeOfStudy=Research| |iTypeOfStudy=1|
#2, |sTypeOfStudy=Education| |iTypeOfStudy=2|
#3, |sTypeOfStudy=Composition| |iTypeOfStudy=3|
#4, |sTypeOfStudy=Performance| |iTypeOfStudy=4|
#5, |sTypeOfStudy=Social Club| |iTypeOfStudy=5|



:Activities
1,[Meetings]
1,[Performance=%iTypeOfCollege%]
1,[Educational Activities]
#Study Specific Activities
1,[Activities=%iTypeOfStudy%]
#This is completely batty, and I was probably drunk when I wrote this code
#that will always crash this table. Make it go away.
1,[Activities=6]

In case you are wondering yes, you can put comments in the center of your group calls. It does no harm and can be quite useful. Before I get too repetitive let me point out the last reason why comments are very important, and should be made as you go along.

;!Research Activities
1, Magical Research into:
1, Historical Research into:
1, [Timing] [Educational Activities]

Magical and Historical Research into: into WHAT!?! Why the heck wouldn’t I leave myself a note onto where I was going with this table? The rest of the table is pretty fleshed out, except for this one little section that leaves no hint on what I was thinking.

Let me rectify the subsection:

#------------------ [Activities Subsection] -------------------
#;Type of Study
#1, |sTypeOfStudy=Research| |iTypeOfStudy=1|
#2, |sTypeOfStudy=Education| |iTypeOfStudy=2|
#3, |sTypeOfStudy=Composition| |iTypeOfStudy=3|
#4, |sTypeOfStudy=Performance| |iTypeOfStudy=4|
#5, |sTypeOfStudy=Social Club| |iTypeOfStudy=5|

;Activities
1,[Meetings]
1,[Performance=%iTypeOfCollege%]
1,[Educational Activities]
#Study Specific Activities
1,[Study Specific Activities=%iTypeOfStudy%]

:Study Specific Activities
1,[Research Activities]
2,[Education Activities]
3,[Composition Activities]
4,[Performance Activities]
5,[Social Activities]

;!Meetings
1,Roundtable Discussions
1,[Rank Display={Dice~1d5+1}] Meeting
1,General Members Meeting
1,[Timing][Meetings]

;!Research Activities
1, Magical Research into:
1, Historical Research into:
1, [Timing] [Educational Activities]

#Performance Education
#Theoretical Education
;Education Activities
1, [Timing] [Rank Display={Dice~1d5+1}] Lecture
1, [Educational Activities]
1, Graduation

#Performance Composition
#Theoretical Composition
;!Composition Activities
1, [Timing] [Rank Display={Dice~1d5+1}] Performance
1, {if~%iOrganizationType% = 1 ? Graduation Performance / [General Activities]}
1, [Educational Activities]

;!Performance Activities
1, [Timing] [Rank Display={Dice~1d5+1}] Performance
1, Galas

;!Social Activities
1, [Timing] Dinner
1, Roundtable Meetings
1, Dances
1, Charity Fund Raisers
1, Potluck Dinner

;Educational Activities
1,[Lectures].
# [symposium]. [Research Projects].

Let’s recap, and put all this in perspective. Comment your table. Comment so that others can follow your logic and quickly add improvements to your code. Comment so that when a new version of TS comes out you can follow your logic if something breaks. Comment so that when you confuse yourself with your logic you can remember why you did something. Comment so that life is good. Comments so that when you come back to your table 4 years later you don’t spend hours saying, WTF? to yourself.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s