summaryrefslogtreecommitdiff
path: root/Documentation/CodingGuidelines
AgeCommit message (Collapse)AuthorFilesLines
2020-04-22Merge branch 'jc/allow-strlen-substitution-in-shell-scripts'Libravatar Junio C Hamano1-2/+0
Coding guideline update. * jc/allow-strlen-substitution-in-shell-scripts: CodingGuidelines: allow ${#posix} == strlen($posix)
2020-03-29CodingGuidelines: allow ${#posix} == strlen($posix)Libravatar Junio C Hamano1-2/+0
The construct has been in POSIX for the past 10+ years, and we have used in t9xxx (subversion) series of the tests, so we know it is at portable across systems that people have run those tests, which is almost everything we'd care about. Let's loosen the rule; luckily, the check-non-portable-shell script does not have any rule to find its use, so the only change needed is a removal of one paragraph from the documentation. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-07Documentation: fix a bunch of typos, both old and newLibravatar Elijah Newren1-2/+2
Reported-by: Jens Schleusener <Jens.Schleusener@fossies.org> Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-07-25Merge branch 'jc/post-c89-rules-doc'Libravatar Junio C Hamano1-3/+23
We have been trying out a few language features outside c89; the coding guidelines document did not talk about them and instead had a blanket ban against them. * jc/post-c89-rules-doc: CodingGuidelines: spell out post-C89 rules
2019-07-18CodingGuidelines: spell out post-C89 rulesLibravatar Junio C Hamano1-3/+23
Even though we have been sticking to C89, there are a few handy features we borrow from more recent C language in our codebase after trying them in weather balloons and saw that nobody screamed. Spell them out. While at it, extend the existing variable declaration rule a bit to read better with the newly spelled out rule for the for loop. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-06-17Merge branch 'es/git-debugger-doc'Libravatar Junio C Hamano1-0/+6
Doc update. * es/git-debugger-doc: doc: hint about GIT_DEBUGGER in CodingGuidelines
2019-05-28doc: hint about GIT_DEBUGGER in CodingGuidelinesLibravatar Emily Shaffer1-0/+6
We check for a handy environment variable GIT_DEBUGGER when running via bin-wrappers/, but this feature is undocumented. Add a hint to how to use it into the CodingGuidelines (which is where other useful environment settings like DEVELOPER are documented). Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-13doc/CodingGuidelines: URLs and paths as monospaceLibravatar Corentin BOMPARD1-2/+5
The current documentation uses both quotes (italics) and backquotes (monospace) to render URLs and pathnames, which is inconsistent. Document a best practice in CodingGuidelines to help reduce inconsistencies in the future. We set the best practice to using backquotes, since: * It is already an established practice. For exemple: $ git grep "'[^']/*[^']'" | wc -l 206 $ git grep '`[^`]/*[^`]`' | wc -l 690 There are false positives on both sides, but after a cursory look at the output of both, it doesn't seem the false positive rate is really higher in the second case. At least, this shows that the existing documentation uses inconsistent formatting, and that it would be good to do something about it. * It may be debatable whether path names need to be typed in monospace but having them in italics is really unusual. Signed-off-by: Corentin BOMPARD <corentin.bompard@etu.univ-lyon1.fr> Signed-off-by: Nathan BERBEZIER <nathan.berbezier@etu.univ-lyon1.fr> Signed-off-by: Pablo CHABANNE <pablo.chabanne@etu.univ-lyon1.fr> Signed-off-by: Matthieu MOY <matthieu.moy@univ-lyon1.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-10-19Merge branch 'jc/how-to-document-api'Libravatar Junio C Hamano1-1/+4
Doc update. * jc/how-to-document-api: CodingGuidelines: document the API in *.h files
2018-10-07Documentation: add shell guidelinesLibravatar Matthew DeVore1-0/+18
Add the following guideline to Documentation/CodingGuidelines: Break overlong lines after "&&", "||", and "|", not before them; that way the command can continue to subsequent lines without backslash at the end. And the following to t/README (since it is specific to writing tests): Pipes and $(git ...) should be avoided when they swallow exit codes of Git processes Signed-off-by: Matthew DeVore <matvore@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-09-29CodingGuidelines: document the API in *.h filesLibravatar Junio C Hamano1-1/+4
It makes it harder to let the API description and the reality drift apart if the doc is kept close to the implementation or the header of the API. We have been slowly migrating API docs out of the Documentation/technical/api-* to *.h files, and the development community generally considers that how inline docs in strbuf.h is done the best current practice. We recommend documenting in the header over documenting near the implementation to encourage people to write the docs that are readable without peeking at the implemention. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-02-08CodingGuidelines: mention "static" and "extern"Libravatar Jeff King1-0/+5
It perhaps goes without saying that file-local stuff should be marked static, but it does not hurt to remind people. Less obvious is that we are settling on "do not include extern in function declarations". It is already the default unless the function was previously declared static (but if you are following a static declaration with an unmarked one, you should think about why you are declaring the thing twice). And so it just becomes an extra noise-word in our header files. We used to give the opposite advice, so there are quite a few "extern" markers in early Git code. But this at least makes a concrete suggestion that we can follow going forward. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-06-04Merge branch 'ab/c-translators-comment-style'Libravatar Junio C Hamano1-5/+5
Update the C style recommendation for notes for translators, as recent versions of gettext tools can work with our style of multi-line comments. * ab/c-translators-comment-style: C style: use standard style for "TRANSLATORS" comments
2017-05-31C style: use standard style for "TRANSLATORS" commentsLibravatar Ævar Arnfjörð Bjarmason1-5/+5
Change all the "TRANSLATORS: [...]" comments in the C code to use the regular Git coding style, and amend the style guide so that the example there uses that style. This custom style was necessary back in 2010 when the gettext support was initially added, and was subsequently documented in commit cbcfd4e3ea ("i18n: mention "TRANSLATORS:" marker in Documentation/CodingGuidelines", 2014-04-18). GNU xgettext hasn't had the parsing limitation that necessitated this exception for almost 3 years. Since its 0.19 release on 2014-06-02 it's been able to recognize TRANSLATOR comments in the standard Git comment syntax[1]. Usually we'd like to keep compatibility with software that's that young, but in this case literally the only person who needs to be using a gettext newer than 3 years old is Jiang Xin (the only person who runs & commits "make pot" results), so I think in this case we can make an exception. This xgettext parsing feature was added after a thread on the Git mailing list[2] which continued on the bug-gettext[3] list, but we never subsequently changed our style & styleguide, do so. There are already longstanding changes in git that use the standard comment style & have their TRANSLATORS comments extracted properly without getting the literal "*"'s mixed up in the text, as would happen before xgettext 0.19. Commit 7ff2683253 ("builtin-am: implement -i/--interactive", 2015-08-04) added one such comment, which in commit df0617bfa7 ("l10n: git.pot: v2.6.0 round 1 (123 new, 41 removed)", 2015-09-05) got picked up in the po/git.pot file with the right format, showing that Jiang already runs a modern xgettext. The xgettext parser does not handle the sort of non-standard comment style that I'm amending here in sequencer.c, but that isn't standard Git comment syntax anyway. With this change to sequencer.c & "make pot" the comment in the pot file is now correct: #. TRANSLATORS: %s will be "revert", "cherry-pick" or -#. * "rebase -i". +#. "rebase -i". 1. http://git.savannah.gnu.org/cgit/gettext.git/commit/?id=10af7fe6bd 2. <2ce9ec406501d112e032c8208417f8100bed04c6.1397712142.git.worldhello.net@gmail.com> (https://public-inbox.org/git/2ce9ec406501d112e032c8208417f8100bed04c6.1397712142.git.worldhello.net@gmail.com/) 3. https://lists.gnu.org/archive/html/bug-gettext/2014-04/msg00016.html Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Acked-by: Jiang Xin <worldhello.net@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-05-08doc: replace a couple of broken gmane linksLibravatar Ævar Arnfjörð Bjarmason1-1/+1
Replace a couple of broken links to gmane with links to other archives. See commit 54471fdcc3 ("README: replace gmane link with public-inbox", 2016-12-15) for prior art. With this change there's still 4 references left in the code: $ git grep -E '(article|thread)\.gmane.org' -- |grep -v RelNotes|wc -l 4 I couldn't find alternative links for those. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-17CodingGuidelines: clarify multi-line brace styleLibravatar Jeff King1-5/+32
There are some "gray areas" around when to omit braces from a conditional or loop body. Since that seems to have resulted in some arguments, let's be a little more clear about our preferred style. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-06-28CodingGuidelines: formatting HEAD in documentationLibravatar Matthieu Moy1-2/+3
The current practice is: git/Documentation$ git grep "'HEAD'" | wc -l 24 git/Documentation$ git grep "\`HEAD\`" | wc -l 66 Let's adopt the majority as a guideline. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-06-08doc: clearer rule about formatting literalsLibravatar Tom Russello1-3/+10
Make the guideline text that we want for our documentation clearer. Signed-off-by: Tom Russello <tom.russello@grenoble-inp.org> Signed-off-by: Erwan Mathoniere <erwan.mathoniere@grenoble-inp.org> Signed-off-by: Samuel Groot <samuel.groot@grenoble-inp.org> Signed-off-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr> Reviewed-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-02-25add DEVELOPER makefile knob to check for acknowledged warningsLibravatar Lars Schneider1-0/+5
We assume Git developers have a reasonably modern compiler and recommend them to enable the DEVELOPER makefile knob to ensure their patches are clear of all compiler warnings the Git core project cares about. Enable the DEVELOPER makefile knob in the Travis-CI build. Suggested-by: Jeff King <peff@peff.net> Signed-off-by: Lars Schneider <larsxschneider@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-04-14Merge branch 'jg/cguide-we-cannot-count'Libravatar Junio C Hamano1-1/+1
* jg/cguide-we-cannot-count: CodingGuidelines: update 'rough' rule count
2015-04-14CodingGuidelines: update 'rough' rule countLibravatar Julian Gindi1-1/+1
Changed inaccurate count of "rough rules" from three to the more generic 'a few'. Signed-off-by: Julian Gindi <juliangindi@gmail.com> Reviewed-by: Eric Sunshine <sunshine@sunshineco.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-13*config.txt: stick to camelCase naming conventionLibravatar Nguyễn Thái Ngọc Duy1-1/+1
This should improve readability. Compare "thislongname" and "thisLongName". The following keys are left in unchanged. We can decide what to do with them later. - am.keepcr - core.autocrlf .safecrlf .trustctime - diff.dirstat .noprefix - gitcvs.usecrlfattr - gui.blamehistoryctx .trustmtime - pull.twohead - receive.autogc - sendemail.signedoffbycc .smtpsslcertpath .suppresscc Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-02-22Merge branch 'jc/conf-var-doc'Libravatar Junio C Hamano1-0/+23
Longstanding configuration variable naming rules has been added to the documentation. * jc/conf-var-doc: CodingGuidelines: describe naming rules for configuration variables config.txt: mark deprecated variables more prominently config.txt: clarify that add.ignore-errors is deprecated
2015-02-11Merge branch 'ah/usage-strings'Libravatar Junio C Hamano1-2/+6
* ah/usage-strings: standardize usage info string format
2015-02-11Merge branch 'jc/coding-guidelines'Libravatar Junio C Hamano1-3/+8
* jc/coding-guidelines: CodingGuidelines: clarify C #include rules
2015-02-02CodingGuidelines: describe naming rules for configuration variablesLibravatar Junio C Hamano1-0/+23
We may want to say something about command line option names in the new section as well, but for now, let's make sure everybody is clear on how to structure and name their configuration variables. The text for the rules are partly taken from the log message of Jonathan's 6b3020a2 (add: introduce add.ignoreerrors synonym for add.ignore-errors, 2010-12-01). Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-01-15CodingGuidelines: clarify C #include rulesLibravatar Junio C Hamano1-3/+8
Even though "advice.h" includes "git-compat-util.h", it is not sensible to have it as the first #include and indirectly satisify the "You must give git-compat-util.h a clean environment to set up feature test macros before including any of the system headers are included", which is the real requirement. Because: - A command that interacts with the object store, config subsystem, the index, or the working tree cannot do anything without using what is declared in "cache.h"; - A built-in command must be declared in "builtin.h", so anything in builtin/*.c must include it; - These two headers both include "git-compat-util.h" as the first thing; and - Almost all our *.c files (outside compat/ and borrowed files in xdiff/) need some Git-ness from "cache.h" to do something Git-ish. let's explicitly specify that one of these three header files must be the first thing that is included. Any of our *.c file should include the header file that directly declares what it uses, instead of relying on the fact that some *.h file it includes happens to include another *.h file that declares the necessary function or type. Spell it out as another guideline item. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-01-14standardize usage info string formatLibravatar Alex Henrie1-2/+6
This patch puts the usage info strings that were not already in docopt- like format into docopt-like format, which will be a litle easier for end users and a lot easier for translators. Changes include: - Placing angle brackets around fill-in-the-blank parameters - Putting dashes in multiword parameter names - Adding spaces to [-f|--foobar] to make [-f | --foobar] - Replacing <foobar>* with [<foobar>...] Signed-off-by: Alex Henrie <alexhenrie24@gmail.com> Reviewed-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-07-16Merge branch 'po/error-message-style'Libravatar Junio C Hamano1-0/+9
* po/error-message-style: doc: give some guidelines for error messages
2014-07-10doc: give some guidelines for error messagesLibravatar Philip Oakley1-0/+9
Clarify error message puntuation to reduce review workload. Signed-off-by: Philip Oakley <philipoakley@iee.org> Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-20CodingGuidelines: avoid "test <cond> -a/-o <cond>"Libravatar Junio C Hamano1-0/+13
The construct is error-prone; "test" being built-in in most modern shells, the reason to avoid "test <cond> && test <cond>" spawning one extra process by using a single "test <cond> -a <cond>" no longer exists. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-02CodingGuidelines: on splitting a long lineLibravatar Junio C Hamano1-0/+55
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-02CodingGuidelines: on comparisonLibravatar Junio C Hamano1-0/+27
There are arguments for writing a conditional as "a < b" rather than "b > a", or vice versa. Let's give guidance on which we prefer. See http://thread.gmane.org/gmane.comp.version-control.git/3903/focus=4126 for the original discussion. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-02CodingGuidelines: do not call the conditional statement "if()"Libravatar Junio C Hamano1-1/+1
The point immediately before it is about having SP after the control keyword. Spell it out as 'an "if" statement' instead. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-02CodingGuidelines: give an example for shell function preambleLibravatar Junio C Hamano1-3/+11
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-02CodingGuidelines: give an example for control statementsLibravatar Junio C Hamano1-0/+11
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-02CodingGuidelines: give an example for redirectionLibravatar Junio C Hamano1-0/+8
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-02CodingGuidelines: give an example for case/esac statementLibravatar Junio C Hamano1-1/+11
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-05-02CodingGuidelines: once it is in, it is not worth the code churnLibravatar Junio C Hamano1-0/+8
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-04-18i18n: mention "TRANSLATORS:" marker in Documentation/CodingGuidelinesLibravatar Junio C Hamano1-0/+10
These comments have to have "TRANSLATORS: " at the very beginning and have to deviate from the usual multi-line comment formatting convention. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-04-08Merge branch 'jl/nor-or-nand-and'Libravatar Junio C Hamano1-2/+2
Eradicate mistaken use of "nor" (that is, essentially "nor" used not in "neither A nor B" ;-)) from in-code comments, command output strings, and documentations. * jl/nor-or-nand-and: code and test: fix misuses of "nor" comments: fix misuses of "nor" contrib: fix misuses of "nor" Documentation: fix misuses of "nor"
2014-03-31Documentation: fix misuses of "nor"Libravatar Justin Lebar1-2/+2
Signed-off-by: Justin Lebar <jlebar@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-02-28CodingGuidelines: mention C whitespace rulesLibravatar Jeff King1-0/+11
We are fairly consistent about these, so most are covered by "follow existing style", but it doesn't hurt to be explicit. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-12-17Merge branch 'jj/doc-markup-hints-in-coding-guidelines' into maintLibravatar Junio C Hamano1-3/+31
* jj/doc-markup-hints-in-coding-guidelines: State correct usage of literal examples in man pages in the coding standards
2013-12-03Merge branch 'jj/doc-markup-hints-in-coding-guidelines'Libravatar Junio C Hamano1-3/+31
* jj/doc-markup-hints-in-coding-guidelines: State correct usage of literal examples in man pages in the coding standards
2013-11-18State correct usage of literal examples in man pages in the coding standardsLibravatar Jason St. John1-3/+31
The man pages contain inconsistent usage of backticks vs. single quotes around options, commands, etc. that are in paragraphs. This commit states that backticks should always be used around literal examples. This commit states that "--" and friends should not be escaped (e.g. use `--pretty=oneline` instead of `\--pretty=oneline`). This commit also states correct usage for typesetting command usage examples with inline substitutions. Thanks-to: Ramkumar Ramachandra <artagnon@gmail.com> Thanks-to: Stuart Rackham <srackham@gmail.com> Thanks-to: Junio C Hamano <gitster@pobox.com> Signed-off-by: Jason St. John <jstjohn@purdue.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-10-14CodingGuidelines: style for multi-line commentsLibravatar brian m. carlson1-0/+8
The style for multi-line comments is often mentioned and should be documented for clarity. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
2013-08-01Provide some linguistic guidance for the documentation.Libravatar Marc Branchaud1-0/+8
This will hopefully avoid questions over which spelling and grammar should be used. Translators are of course free to create localizations for specific English dialects. Signed-off-by: Marc Branchaud <marcnarc@xiplink.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-05-10CodingGuidelines: Documentation/*.txt are the sourcesLibravatar Dale Worley1-2/+4
People not familiar with AsciiDoc may not realize they are supposed to update *.txt files and not *.html/*.1 files when preparing patches to the project. Signed-off-by: Dale Worley <worley@ariadne.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-03-21CodingGuidelines: our documents are in AsciiDocLibravatar Junio C Hamano1-0/+3
Before talking about notations such as optional [--option] enclosed in brackets, state that the documents are in AsciiDoc and processed into other formats. Signed-off-by: Junio C Hamano <gitster@pobox.com>