Code guidelines

I have adopted the following practices:

Strict

Every JavaScript page has this at the top:

"use strict"

This means the JavaScript interpreter will be in strict mode and will object to, for example, variables that are not declared. This is generally regarded as best practice.

Content Security Policy

  <meta http-equiv="Content-Security-Policy" content="
    default-src 'self';
    style-src 'unsafe-inline' 'self' https://fonts.googleapis.com https://ajax.googleapis.com;
    font-src 'self' https://fonts.gstatic.com;
    script-src 'unsafe-inline' 'self' https://ajax.googleapis.com;
    img-src 'self' https://ajax.googleapis.com;"
  >

This means no eval and no accessing other libraries. Of course, authors can update this if they require.

If you link to images on external sites (perhaps to get around the size limit on the textadventures web site), you will need to include the other sites in the last line.

Code Style

I use two space indents. It is what I am used to! I like my code to be compact so I can see as much as possible in one screen.

I generally prefer to use // for comments, and only to use /* and */ when commenting out a block of code temporarily. Related, if I decide a block of code is not needed, I will block it off first and make sure it really is not used. If you find a commented out block of code, that is probably the reason.

Best practice is to use const to declare any variable that does not change and let if it does (the variable inside for/of and for/in loops should use const, but I got in the habit of using let from other for loops, so most do that). There should be no reason to use var. Note that in strict mode, all variables must be declared before use.

Semi-colons

Semi-colons are optional in JavaScript (except in the trivial case of for (;;) loops), however, this seems to be something that a lot of people have strong opinions on one way or another, and I appreciate I am in something of a minority here. But being in a minority does not make you wrong!

Lint tools all seem to advocate them, and it is what I am used to, so I used them when I started this. I now take the view that if they are optional, they are not needed, so why bother? People say it is easier to read, but how can adding extra punctuation at the end of nearly every line make it easier to read? It is just adding visual noise.

Advocates of semi-colons will point to examples where JavaScript will erroneously assume a semi-colon where it should not. But it will do so regardless of how much you have peppered your code with the things elsewhere. The trick is not to add unneeded semicolons; the trick is to not break your line of code in stupid places. Keep a line of code on one line, and you should be fine - and it will be easier to read.

There are edge cases where a semi-colon can be necessary, but these all seem to be when a line starts with a (, [ or { and you have split a statement across two lines or the interpreter thinks you have. These are generally things you can avoid doing (if you use Immediately-invoked Function Expression, then be careful, but if you are using them, you probably know more JavaScript than I do, and you can work out when you need semi-colons for yourself).

If you do want to start a line with (, [ or {, put a semi-colon at the start of that line. That line is the problem, so it makes sense to give responsibility for fixing it to that line and not the next/previous line. It will be unpopular, but it is one semi-colon where it is needed, rather than tens of thousands where they are not.

Language support

I try to build in support for other languages, which means using a constant or function defined in lang-en.js, rather than hard-coded in the lib file.

The exception to this is error messages produced by bugs in the game. Quest 5 error messages are in English only (though most make little sense anyway), so there is precedent. I would like error messages to be as useful as possible, and that potentially means a lot of them, and to make them traceable, they should be unique. That is much easier if they are just in English. In theory the player will never see them; these are only reporting bugs.