docs: make a start on query debugging topic

[jf205]

This PR adds an incomplete draft of a topic currently named 'Query writing: common issues'.
I was prompted to start writing this following various discussions over recent weeks.
At the moment it contains a pretty sparse list of QL constructs to avoid when writing queries.
I would very much welcome any suggestions about what else to include.

[jf205]

@max: before you go on leave would you mind having a quick look at this topic on debugging QL performance please?

Can you think of anything that should be added? (bearing in mind that it is intended to be an introductory topic).

[felicitymay]

It would be really good if it were possible to review this so that it can be published in early November.

@lcartey - do you have any more feedback or suggestions for other reviewers who might be able to help with other issues to watch out for?

[jf205]

This has been sitting around for a while, but I think this is worth getting into the rc/1.23 branch. We can always expand it later (fyi @shati-patel).

@max-schaefer, would you mind sanity checking and merging for me please?

[max-schaefer]

I agree that this would be very useful to have! I have a number of suggestions.

[max-schaefer]

This example is a bit too contrived. How about this?

---

For instance, consider the following predicate that checks whether a Java method m may access a field f:

predicate mayAccess(Method m, Field f) {
  f.getAnAccess().getEnclosingCallable() = m
  or
  not exists(m.getBody())
}

The predicate holds if m contains an access to f, but also conservatively assumes that methods without bodies (for example native methods) may access any field at all.

What this means, however, is that if m is a native method, then the table computed by mayAccess contains a row m, f for all fields f in the code base, resulting in a potentially very large table.

[max-schaefer]

The first example above now has this form, so perhaps this paragraph can be shortened.

[jf205]

Thanks for the suggestions @max-schaefer! I think they have all been addressed now.

[max-schaefer]

Great! Two more minor suggestions.

[jf205]

Thanks @max-schaefer.

@lcartey requested two minor changes on an earlier iteration of this topic. I've made those changes, but we'll need to wait for approval but it can be merged.

[shati-patel]

I'd like to have a quick look too - will review/merge after lunch!

[shati-patel]

Thanks, this will be a useful topic to have!

I've made a few suggestions, but feel free to ignore them if you think they're unnecessary (apart from the typo).

[jf205]

Thanks @shati-patel 👀

comments addressed

[shati-patel]

Thank you!