What do you do when the code you’ve written does not compile and the compiler error output directs you to a page in the Documentation that does not explain how to write it correctly?
This question is based on my personal experience during the past hour, but it’s also a general question that I think could be explored in a section of the Handbook. (I’m still working on revisions for the Handbook.)
For many years I’ve been aware that the I7 Documentation is not very good. That’s why I wrote the Handbook. But beyond that, it’s hard for me to avoid the impression that the syntax of Inform 7/10 is, in many cases, rather obscure.
I’m not going to try to give an example. I’m just going to ask the general question, “What do you do when the error message is not helpful?”
consult the docs and examples of extensions I’m using if it seems related to them
consult the source of the Standard Rules / Basic Inform / English Language / other extensions I may have included
comment out the inclusion of various extensions and the code that depends on it
search here. a lot. search some more. So much searching. Bookmark things Zarf or Ron Newcomb or Brady Garvin said more than a decade ago that don’t solve my problem of the moment. Search some more.
try to find an example or an extension that does correctly what I’m hoping to do (I have the doc examples and a huge number of extensions and a bunch of games whose source is public under one big directory for easy searching)
look in Syntax.preform to see if it sheds any light on syntax
since 10.1, look at the I7 source itself. I still haven’t tried to go through end-to-end, but I’ve found several cases where something I’d always wished was documented about the language acually is, but only there
realize I’ve put in an unreasonable amount of work before deciding to just ask a question here
try to come up with a concise example that demonstrates the problem so I can ask a productive question here, and a noticeable amount of the time, I figure things out during that process
finally actually ask a question here
Your question referred to compiler errors and syntax problems, but I’ll keep on going about various runtime/behavior problems… a bunch of the above still apply, plus…
look directly at the I7 compiler’s I6 output
look at the kit / I6 template layer source
modify extensions I’m using and / or the underlying I6 to add say / print statements. Lots of print statements. More print statements. So many print statements.
1.) Reread the error until the words no longer make sense and sound like as many formless sounds in my head.
2.) Start cutting and pasting bits of the code in and out of the project trying to isolate the source of the headache.
3.) Realize I wasn’t being careful and had created an additional unrelated error due to sloppy c&p.
5.) Spend 30-60 minutes solving the problem I created myself.
6.) Contemplate rewriting the game in a way that it would no longer need the offending bit of code.
8.) Panic some more.
9.) Repeat steps 1-8 as needed.
Nine times out of ten I find I7’s error messages helpful. The rest of the time it’s my own fault — I should have flooded the river plain. Of course! Why didn’t I flood the river plain?! Schoolboy error!
It’s almost always punctuation for me. I’m an imprecise typist, and I don’t attempt a lot of what I consider to be sophisticated code.
Then, as has been said, I start commenting out things.
Otherwise, a clean project with as little as possible besides the offending code.
Next, a search!
I dislike asking for help, especially with regard to mistakes I’ve made. It’s a character flaw that has implications beyond my hobbies. So I spend a lot of time figuring things out that someone could easily explain. I enjoy figuring things out, though, so that’s alright. Asking “how” questions, on the other hand, I’ve done several times.
I would like to re-re-emphasize this and add that the easiest way I’ve found to achieve this is to compile every time I add even something small. One definition, new object, rule, phrase – any one chunk of code.
This should only be a pain if you’re currently working on the next Blue Lacuna.
One of the most confounding errors are name collisions, for instance with adjectives, or where one thing has a name that is a subset of another. This gets pretty bad when the conflict is across extensions.
I have a couple of strategies to deal with difficult situations: (1) compile often. I like to compile every sentence or two. (2) commit to a source repository often, so you can easily look at diffs or do a binary search.
It took a while before I learned this, but it is the single most valuable piece of advice in this thread, I think. I’ve had WAAAAY too many times where punctuation got weird and Inform got confused and gave me an incorrect error message. Compiling every time you add a piece of code (even just a description) is the way to avoid heartbreak.
I’ll turn what I added most recently into a comment and work backwards until it compiles, then if there’s multiple lines of code in the part that causes the problem, I’ll narrow it down to the specific sentence or phrase. I’ll usually try a couple different permutations/wordings of the same idea (bc I’m stubborn), then I turn to the forum.
Thanks, everyone. Good discussion. In the situation I was smacking my head about last night, I was trying to edit some code I wrote years ago (for my no-longer-working Spellcasting extension). I had tried to write it so that an NPC could also be told to learn and cast a spell. As a result, I had some instead rules in the Example game that included lines like, “Instead of an actor spellcasting…” I couldn’t figure out how to refer to the actor in the code that followed, to check whether the actor had learned the spell. Nothing compiled. And the compiler error message directed me to a page that was utterly useless.
I’m going to research that topic separately, because it belongs in the Handbook.
During the night I figured out that Spellcasting is a useless idea as an extension in any case. It’s better to just write your own game code for casting spells. Much less messy.