Docs: Recommend EditorConfig.

Note that we use EditorConfig in the WSDG and README.developer, and that
you should make sure your editor uses it. Recommend 4 space indentation
more strongly. Ping #17253.

Reorder and reword the coding style sections of each document while
we're here.
This commit is contained in:
Gerald Combs 2021-02-22 13:49:30 -08:00
parent 8ccbdb786a
commit eceff254b6
2 changed files with 26 additions and 37 deletions

View File

@ -682,43 +682,36 @@ ws_, wslua_, wmem_ and wtap_.
5. White space convention.
Most of the C and C++ files in Wireshark use 4-space or 2-space indentation.
When creating new files you are you are strongly encouraged to use 4-space
indentation for source code in order to ensure consistency between files.
Please avoid using tab expansions different from 8 column widths, as not all
text editors in use by the developers support this. For a detailed
discussion of tabs, spaces, and indentation, see
text editors in use by the developers support this. For a detailed discussion
of tabs, spaces, and indentation, see
http://www.jwz.org/doc/tabs-vs-spaces.html
Most of the files in Wireshark tend to use 2-space or 4-space indentation. When
creating a new file you are free to choose an indentation logic but you are
encouraged to use 4-space indentation for C/C++ source to keep inconsistency
between files to a minimum.
We use EditorConfig (http://editorconfig.org) files to provide formatting
hints. Most editors and IDEs support EditorConfig, either directly or via
a plugin. If yours requires a plugin we encourage you to install it. Our
default EditorConfig indentation style for C and C++ files is 4 spaces.
Each file should have a short comment (modelines) on the indentation logic at
the end of the file. See
Many files also have a short comment (modelines) on the indentation logic at
the end of the file. This was required in the past but has been superseded by
EditorConfig. See
https://www.wireshark.org/tools/modelines.html
for guidance.
A complementary and arguably better alternative to modelines is
EditorConfig (http://editorconfig.org). The default EditorConfig indentation
style is defined in the .editorconfig file placed on the root of the project
source code tree (4-space indentation for C). One advantage of following the
default style is that no additional EditorConfig settings are required for new
files. If your file does not follow this style please add a file-specific
setting overriding the default style to a separate .editorconfig configuration
file placed in the source file directory.
Some IDEs and text editors have built-in EditorConfig support and many more
have plugins available (links at http://editorconfig.org).
for more information.
Please do not leave trailing whitespace (spaces/tabs) on lines.
When editing an existing file, try following the existing indentation
logic and even if it very tempting, never ever use a restyler/reindenter
utility on an existing file. If you run across wildly varying
indentation styles within the same file, it might be helpful to send a
note to wireshark-dev for guidance.
Quite a bit of our source code has varying indentation styles. When editing an
existing file, try following the existing indentation logic. If you wish to
convert a file to 4 space indentation, please do so in its own commit and be
sure to remove its .editorconfig entry so that the default setting takes
effect.
6. Compiler warnings

View File

@ -323,15 +323,9 @@ on using the <<ChToolsDebugger, Debugger Tools>>.
[[ChSrcChange]]
=== Make Changes To The Wireshark Sources
As the Wireshark developers are working on many different platforms, a lot of
editors are used to develop Wireshark (emacs, vi, Microsoft Visual Studio
and many, many others). Theres no "standard" or "default" development
environment.
There are several reasons why you might want to change Wiresharks sources:
There are several reasons why you might want to change the Wireshark
sources:
* Add support for a new protocol (a new dissector)
* Add support for a new protocol (i.e., add a new dissector)
* Change or extend an existing dissector
@ -339,10 +333,12 @@ sources:
* Implement a glorious new feature
The internal structure of the Wireshark sources will be described in
<<PartDevelopment>>.
Wiresharks developers work on a variety of different platforms and use a variety of different development environments.
Although we we don't enforce or recommend a particular environment, your editor should support https://editorconfig.org/[EditorConfig] in order to make sure you pick up the correct indentation style for any files that you might edit.
.Ask the _wireshark-dev_ mailing list before you start a new development task.
The internal structure of the Wireshark sources are described in <<PartDevelopment>>.
.Ask the {wireshark-dev-list-email} mailing list before you start a new development task.
[TIP]
====
If you have an idea what you want to add or change its a good idea to