From eceff254b64d90b921801a1c28d0f2a76debb0a0 Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Mon, 22 Feb 2021 13:49:30 -0800 Subject: [PATCH] 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. --- doc/README.developer | 45 +++++++++------------- docbook/wsdg_src/WSDG_chapter_sources.adoc | 18 ++++----- 2 files changed, 26 insertions(+), 37 deletions(-) diff --git a/doc/README.developer b/doc/README.developer index 6eacc1c481..5fa4c76bcd 100644 --- a/doc/README.developer +++ b/doc/README.developer @@ -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 diff --git a/docbook/wsdg_src/WSDG_chapter_sources.adoc b/docbook/wsdg_src/WSDG_chapter_sources.adoc index 4da83b178d..d543d27d3a 100644 --- a/docbook/wsdg_src/WSDG_chapter_sources.adoc +++ b/docbook/wsdg_src/WSDG_chapter_sources.adoc @@ -323,15 +323,9 @@ on using the <>. [[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). There’s no "standard" or "default" development -environment. +There are several reasons why you might want to change Wireshark’s 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 -<>. +Wireshark’s 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 <>. + +.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 it’s a good idea to