These guidelines may not be correct, but show part of the currently used knowledge regarding ANTLR4. Improvements are even big changes to these may be appropriate, in order to fix big misconceptions regarding ANTLR4.

Always split grammar into parser und lexer files, as otherwise just getting it running at all causes problems. Do not use string constants in parser files, as these are hard to get working.

In order to match generic strings in parsers one should use a dedicated parser rule for each such string type. This allows one to add every relevant token of the lexer into it, after the fact.

Avoid using optional parser rules, that at least partly can match any characters, as these destroy most parsing error messages of ANTLR4 and therefore makes it a lot harder to understand syntax errors. See (.)*? Keysymbol_at Keyword_JavaLegacyArtifact (.)*? EOF as an example.

Do not define tokens, that can match to a zero length string, as this causes OutOfMemoryError exceptions. Therefore, do not define tokens with one element and * as qualifier.