Random comments

[ltratt]

Do not merge this ever, under any circumstances -- this is not a normal PR!!!

This is not a PR intended for merge: it's a complete repo code review. Inevitably it's shallow, but it's still thrown up some interesting things. Overall, I'm pretty happy with the code, but we can always improve things :)

There's a mix of things in here. Sometimes I've rephrased a comment; sometimes I've asked a question; less often I have a code change suggestion. So sometimes you can probably just copy an edited thing into your own PR; but sometimes we'll have to have a debate here to decide the way forwards.

What I suggest is that @ptersilie and @vext01 go through each bit of the diff and we use the nomal GitHub comments to decide on things. Then we can open up one or more PRs that address the valid comments in this PR.

Some general comments, in no particular order:

1. We use hard-coded constants a bit more often than I'd like (e.g. Local(0) for the interpreter context). We should be careful to weed as many of these out as possible (I won't have found all of them!) and make sure we don't introduce any more ni future.
2. There were some completely redundant comments of the form "// Does x" for x. Let's kill those.
3. A few functions and structs could do with documenting and/or better documenting.
4. Similarly, I think we should expect all non-test files to have a doc-comment at the top to explain a bit better what the file's contents are.
5. We've got a curious mix of really-well commented code and sparsely/poorly commented code. I think we need to be a bit more ruthless in future code review at ensuring that complex things have good comments. That's both a quantity (sometimes we just don't say enough!) and quality issue (we have quite a few comments that I could make little sense of).

Overall, the aim of this is to make our future selves happier at what our current selves did :) Bear in mind that I'm not familiar with large chunks of the repo, and so some of my comments will be inane, incorrect, or perhaps plain bonkers.

[bjorn3]

Is there anything not yet fixed?

[ltratt]

@ptersilie Any thoughts on @bjorn3's question?

[ptersilie]

I've resolved all the discussions I've dealt with. There's still 3 other discussions which I think @vext01 has fixed, but not yet marked as resolved. So I think this PR is done, though I'd like @vext01 to confirm as well.

[vext01]

Resolved discussions.

[vext01]

Sorry, wrong button.

[vext01]

Can we close this?

[ltratt]

I believe this is now completed, so I'm closing it.