Minor coding policy document fixes.

Ironically make the document formatting more consistent and remove
some trailing whitespace.

Changed "When it Rome.." title since may not have the same meaning in
other languages as it does in English.  Also add table of contents to
this section for linking purposes.
This commit is contained in:
Wayne Stambaugh 2020-05-27 09:05:54 -04:00
parent 53360acc3d
commit 9817b63f66
1 changed files with 12 additions and 11 deletions

View File

@ -87,7 +87,7 @@ you can still commit:
git commit --no-verify git commit --no-verify
### Correcting Formatting Errors ## {#correcting-formatting-errors} ### 1.3.1 Correcting Formatting Errors ### {#correcting-formatting-errors}
There is a Git aliases file that provides the right commands to show and correct There is a Git aliases file that provides the right commands to show and correct
formatting errors. Add to your repository config by running this command from formatting errors. Add to your repository config by running this command from
@ -108,6 +108,7 @@ other uses:
when interactive-rebasing): when interactive-rebasing):
* `check_coding.sh --amend [--diff]` * `check_coding.sh --amend [--diff]`
# 2. Naming Conventions # {#naming_conventions} # 2. Naming Conventions # {#naming_conventions}
Before delving into anything as esoteric as indentation and formatting, Before delving into anything as esoteric as indentation and formatting,
naming conventions need to be addressed. This section does not attempt naming conventions need to be addressed. This section does not attempt
@ -214,9 +215,10 @@ us.
## 2.8 Use of 'auto' ## ## 2.8 Use of 'auto' ##
We do -not- use `auto` to reduce repetition. We do use it to increase We do -not- use `auto` to reduce repetition. We do use it to increase
readability. This generally means -only- use `auto` where std::lib gets readability. This generally means -only- use `auto` where std::lib gets
overly verbose (such as iterators or `std::make_shared`), or when not using overly verbose (such as iterators or `std::make_shared`), or when not using
`auto` would cause line-wraps that can't otherwise be avoided. `auto` would cause line-wraps that can't otherwise be avoided.
# 3. Commenting # {#commenting} # 3. Commenting # {#commenting}
Comments in KiCad typically fall into two categories: in line code Comments in KiCad typically fall into two categories: in line code
comments and Doxygen comments. In line comments have no set formatting comments and Doxygen comments. In line comments have no set formatting
@ -496,11 +498,11 @@ reject clang-format's suggested changes, if you use it:
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
## 4.10 Lamdas ## {#lamda_formatting} ## 4.10 Lamdas ## {#lamda_formatting}
The braces and statements of the body should be indented as you would a method, The braces and statements of the body should be indented as you would a method,
with the braces lined up under the capture block: with the braces lined up under the capture block:
~~~~~~~~~~~~~{.cpp} ~~~~~~~~~~~~~{.cpp}
auto belowCondition = []( const SELECTION& aSel ) auto belowCondition = []( const SELECTION& aSel )
{ {
return g_CurrentSheet->Last() != g_RootSheet; return g_CurrentSheet->Last() != g_RootSheet;
}; };
@ -509,8 +511,8 @@ with the braces lined up under the capture block:
or: or:
~~~~~~~~~~~~~{.cpp} ~~~~~~~~~~~~~{.cpp}
auto belowCondition = auto belowCondition =
[]( const SELECTION& aSel ) []( const SELECTION& aSel )
{ {
return g_CurrentSheet->Last() != g_RootSheet; return g_CurrentSheet->Last() != g_RootSheet;
}; };
@ -596,12 +598,11 @@ is exposed in the header file, merely by including that one header
file. file.
# 7. When in Rome... # # 7. When in Doubt... # {#when_in_doubt}
Anywhere there are multiple acceptable options, follow the formatting When editing existing source code files and there are multiple acceptable
elsewhere in the same file. code formatting options or no formatting is defined, follow the existing
formatting in the file.
If you encounter a situation that has no guidance, follow the formatting
elsewhere in the same file.
# 8. I Wrote X Lines of Code Before I Read This Document # {#x_lines} # 8. I Wrote X Lines of Code Before I Read This Document # {#x_lines}
It's OK. We all make mistakes. Fortunately, KiCad provides a It's OK. We all make mistakes. Fortunately, KiCad provides a