From 8f01cf0269d1e188981edf6d693cf2fcd82f7291 Mon Sep 17 00:00:00 2001 From: Akim Demaille Date: Sun, 12 Apr 2020 18:28:34 +0200 Subject: doc: more about the coding style * README-hacking.md: here. (Troubleshooting): New. --- README-hacking.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) (limited to 'README-hacking.md') 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 -- cgit v1.2.1