diff options
author | Jim Meyering <meyering@redhat.com> | 2010-04-16 08:45:58 +0200 |
---|---|---|
committer | Jim Meyering <meyering@redhat.com> | 2010-04-16 08:45:58 +0200 |
commit | 2018d0e41f8f2821ed176b71c9e910050c436d94 (patch) | |
tree | 271c76a5457ed76aa1e8f512da63a507e0d434e8 /HACKING | |
parent | c3f21e894374d071f421215d4f51523fb4816e7d (diff) | |
download | grep-2018d0e41f8f2821ed176b71c9e910050c436d94.tar.gz |
maint: update init.sh and HACKING
* HACKING: Sync from coreutils.
* tests/init.sh: Update from gnulib.
Diffstat (limited to 'HACKING')
-rw-r--r-- | HACKING | 105 |
1 files changed, 103 insertions, 2 deletions
@@ -233,6 +233,107 @@ Try to make the summary line fit one of the following forms: maint: change-description +Curly braces: use judiciously +============================= +Omit the curly braces around an "if", "while", "for" etc. body only when +that body occupies a single line. In every other case we require the braces. +This ensures that it is trivially easy to identify a single-*statement* loop: +each has only one *line* in its body. + +Omitting braces with a single-line body is fine: + + while (expr) + single_line_stmt (); + +However, the moment your loop/if/else body extends onto a second line, +for whatever reason (even if it's just an added comment), then you should +add braces. Otherwise, it would be too easy to insert a statement just +before that comment (without adding braces), thinking it is already a +multi-statement loop: + + while (true) + /* comment... */ // BAD: multi-line body without braces + single_line_stmt (); + +Do this instead: + + while (true) + { /* Always put braces around a multi-line body. */ + /* explanation... */ + single_line_stmt (); + } + +There is one exception: when the second body line is not at the same +indentation level as the first body line. + + if (expr) + error (0, 0, _("a diagnostic that would make this line" + " extend past the 80-column limit")); + +It is safe to omit the braces in the code above, since the +further-indented second body line makes it obvious that this is still +a single-statement body. + +To reiterate, don't do this: + + if (expr) + while (expr_2) // BAD: multi-line body without braces + { + ... + } + +Do this, instead: + + if (expr) + { + while (expr_2) + { + ... + } + } + +However, there is one exception in the other direction, when even a +one-line block should have braces. That occurs when that one-line, +brace-less block is an "else" block, and the corresponding "then" block +*does* use braces. In that case, either put braces around the "else" +block, or negate the "if"-condition and swap the bodies, putting the +one-line block first and making the longer, multi-line block be the +"else" block. + + if (expr) + { + ... + ... + } + else + x = y; // BAD: braceless "else" with braced "then" + +This is preferred, especially when the multi-line body is more than a +few lines long, because it is easier to read and grasp the semantics of +an if-then-else block when the simpler block occurs first, rather than +after the more involved block: + + if (!expr) + x = y; /* more readable */ + else + { + ... + ... + } + +If you'd rather not negate the condition, then add braces: + + if (expr) + { + ... + ... + } + else + { + x = y; + } + + Use SPACE-only indentation in all[*] files ========================================== We use space-only indentation in nearly all files. @@ -310,9 +411,9 @@ Nearly every significant change must be accompanied by a test suite addition that exercises it. If you fix a bug, add at least one test that fails without the patch, but that succeeds once your patch is applied. If you add a feature, add tests to exercise as much of the new code -as possible. Note to run tests/newtest in isolation you can do: +as possible. Note to run tests/new-test in isolation you can do: - (cd tests && make check TESTS=newtest VERBOSE=yes) + (cd tests && make check TESTS=new-test VERBOSE=yes) There are many tests in the tests/ directories. Use one of the init.sh-using scripts as a template. |