Talk:S2 Guide: Troubleshooting
I think this will be unbelievably helpful to people new to the compiler and to compiling in general!
Forgetting to declare a variable
Might need a change to orient the reader to the word traceback: "The traceback afterwards probably isn't too useful to us most people, however." The current wording might make them think that they're supposed to already know what a traceback is.
Suggest it be more like "After the error message is a section of lines called the traceback, which probably won't be too useful to most people."
Forgetting the semicolon
I had trouble getting the gist of the splitting statements over two lines stuff -- possibly because I rarely ever remember to do that in my own sloppy code (making me a good test reader in this scenario?).
"That's because the compiler doesn't look at line breaks to figure out where statements end, it looks at semi-colons for that. This means that you can split a single statement over two lines, if you wanted to. Here's an example of that statement (properly ended) across two lines:
"So a line that doesn't end in a semi-colon is not automatically a problem for the compiler -- but when the next line doesn't make sense as a continuation of the statement, it will trigger an error. To fix this problem, we need to put a semicolon at the end of the appropriate line:"
Not putting $ in front of a variable
I found the explanation a bit confusing. Suggestion:
"Why was the compiler expecting an open parenthesis (() there? Without $ in front of test, the compiler doesn't know to treat it as a variable. It instead treats test as a global function, and function calls require parentheses, e.g. test().
"Since that error message is pretty confusing, the best way to figure out the problem is to examine the line and run through the Syntax Checklist listed above. We'll find that we've broken the rule about using $ when we're accessing variables."
Anywhere a bracket set is announced to pinpoint a character in the code (example: "I'm going to put a bracket set ()") could you try formatting the brackets with tt? And maybe separating them by a space? It would be nice if they stood out better from the surrounding parentheses and looked less like a single rectangle character.
Do you think it would be worthwhile to add a section on the error you get when you use $ in front of a variable name in the line declaring it? This is a mistake I make when I've been using other languages a lot and then switch back to S2.