doc: more about the coding style

* README-hacking.md: here.
(Troubleshooting): New.

1 files changed, 46 insertions, 0 deletions

diff --git a/README-hacking.md b/README-hacking.md
index 978163da..34d09903 100644
--- a/README-hacking.md
+++ b/README-hacking.md
@@ -44,6 +44,9 @@ However, make files, ChangeLog, and some regular expressions require tabs.
 Also, test cases might need to contain tabs to check that Bison properly
 processes tabs in its input.
 
+Prefer "res" as the name of the local variable that will be "return"ed by
+the function.
+
 ### Bison
 Follow the GNU Coding Standards.
 
@@ -71,9 +74,21 @@ Use `*_t` for types, especially for `yy*_t` in which case we shouldn't worry
 about the C standard introducing such a name.
 
 #### C++
+Follow the C++ Core Guidelines
+(http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines).  The Google
+ones may be interesting too
+(https://google.github.io/styleguide/cppguide.html).
+
+Our enumerators, such as the kinds (symbol and token kinds), should be lower
+case, but it was too late to follow that track for token kinds, and symbol
+kind enumerators are made to be consistent with them.
+
 Use `*_type` for type aliases.  Use `foo_get()` and `foo_set(v)` for
 accessors, or simply `foo()` and `foo(v)`.
 
+Use the `yy` prefix for private stuff, but there's no need for it in the
+public api.  The `yy` prefix is already taken care of via the namespace.
+
 #### Java
 We follow https://www.oracle.com/technetwork/java/codeconventions-150003.pdf
 and https://google.github.io/styleguide/javaguide.html.  Unfortunately at
@@ -89,6 +104,11 @@ Don't use the "yy" prefix for public members: "getExpectedTokens", not
 ## Commit Messages
 Imitate the style we use.  Use `git log` to get sources of inspiration.
 
+If the changes have a small impact on Bison's generated parser, embed these
+changes in the commit itself.  If the impact is large, first push all the
+changes except those about src/parse-gram.[ch], and then another commit
+named "regen" which is only about them.
+
 ## Debugging
 Bison supports tracing of its various steps, via the `--trace` option.
 Since it is not meant for the end user, it is not displayed by `bison
@@ -241,6 +261,32 @@ These files don't change very often in Autoconf, so it should be relatively
 straight-forward to examine the differences in order to decide whether to
 update.
 
+## Troubleshooting
+
+Bison is self-hosted: its parser is generated by Bison.  We don't force
+ourselves to use the previous release of Bison, we use the current git
+master for several reasons:
+- dogfooding: let Bison be its first user
+- monitoring: seeing the diff on the generated parsers with git is very
+  helpful, as it allows to see easily the impact of the changes on a real
+  case parser.
+
+If you are unlucky the generated files, src/parse-gram.[ch], may be older
+than their source, src/parse-gram.y.  And your current version of Bison
+might not be able to grok it.  In that case, first refresh the generated
+files:
+
+    $ touch src/parse-gram.[ch]
+
+Then proceed.
+
+In case you wrecked your current copy of the parser, get back the previous
+version, compile bison, then force it to recreate the files:
+
+    $ git checkout HEAD^ src/parse-gram.[ch]
+    $ make -C _build
+    $ touch src/parse-gram.y
+    $ make -C _build
 
 
 Test Suite