source: subsurface/CodingStyle

Mtestandroid_testdcDownloadforatdotdeiosmergeKirigamiPortpictimeshifttestTomaztestingv4.5-branch
Last change on this file was f09b46d, checked in by Dirk Hohndel <dirk@…>, 2 years ago

CodingStype?: add explanation how to install the QtCreator? settings

Signed-off-by: Dirk Hohndel <dirk@…>

  • Property mode set to 100644
File size: 8.6 KB
Line 
1Coding Style
2============
3
4Here are some of the basics that we are trying to enforce for our coding
5style. The existing code (as of the commit that adds these lines) is not
6yet fully consistent to these rules, but following these rules will make
7sure that no one yells at you about your patches.
8
9We have a script that can be used to reformat code to be reasonably close
10to these rules; it's in scripts/whitespace.pl - this script requires
11clang-format to be installed (which sadly isn't installed by default on
12any of our platforms; even on Mac where clang is the default compiler).
13
14At the end of this file are some ideas for your .emacs file (if that's
15your editor of choice) as well as for QtCreator. If you have settings for
16other editors that implement this coding style, please add them here.
17
18Basic rules
19===========
20
21- all indentation is tabs (set to 8 char) with the exception of
22  continuation lines that are alligned with tabs and then spaces
23
24- all keywords followed by a '(' have a space in between
25
26        if (condition)
27
28        for (i = 0; i < 5; i++)
29
30- function calls do NOT have a space between their name and argument
31
32        i = some_function(argument);
33
34- usually there is no space on the inside of parenthesis (see examples
35  above)
36
37- function / method implementations have their opening curly braces in
38  column 1
39
40- all other opening curly braces follow at the end of the line, with a
41  space separating them:
42
43        if (condition) {
44                dosomething();
45                dosomethingelse();
46        }
47
48- both sides of an if / else clause either use or do not use curly braces:
49
50        if (condition)
51                i = 4;
52        else
53                j = 6;
54
55        if (condition) {
56                i = 6;
57        } else {
58                i = 4;
59                j = 6;
60        }
61
62- use space to make visual separation easier
63
64        a = b + 3 + e / 4;
65
66- continuation lines have the operator / comma at the end
67
68        if (very_long_conditiont_1 ||
69            condition_2)
70
71        b = a + (c + d +
72                 f + z);
73
74- in a C++ constructor initialization list, the colon is on the same line and
75  continuation lines are aligned as the rule above:
76
77        ClassName::ClassName() : x(1),
78                y(2),
79                z(3)
80        {
81        }
82
83- unfortunate inconsistency:
84  -- C code usually uses underscores to structure names
85
86        variable_in_C
87
88  -- C++ code usually uses camelCase
89
90        variableInCPlusPlus
91
92  where the two meet, use your best judgment and go for best consistency
93  (i.e., where does the variable "originate")
94
95- switch statements with blocks are a little bit special (to avoid indenting
96  too far)
97
98        switch (foo) {
99        case FIRST:
100                whatever();
101                break;
102        case SECOND: {
103                int i;
104                for (i = 0; i < 5; i++)
105                        do_something(i);
106        }
107        }
108
109- variable declarations
110  in C code we really like them to be at the beginning of a code block,
111  not interspersed in the middle.
112  in C++ we are a bit less strict about this - but still, try not to go
113  crazy.
114
115- text strings
116  The default language of subsurface is US English so please use US English
117  spelling and terminology.
118  Where at all possible strings should be passed to the tr() function to enable
119  translation into other languages.
120
121  -- like this
122        QString msgTitle = tr("Submit user survey.");
123
124  -- rather than
125        QString msgTitle = "Submit user survey.";
126
127
128- UI text style
129  These guidleines are designed to ensure consitency in presentation within
130  Subsurface.
131  Only the first word of multi-word text strings should be captalized unless
132  a word would normally be capitalized mid-sentance, like Africa. This applies
133  to all UI text including menus, menu items, tool-tips, button text and label
134  text etc. e.g. "Check for updates" rather than "Check for Updates".
135  We also captialize Subsurface (NOTE: not SubSurface) when referring to the
136  application itself.
137  Abbreviations should end with a period, e.g. "temp." not "temp" for
138  temperature
139  Numerals in chemical formulae should use subscript characters e.g. O₂ not O2
140  Partial pressures in Subsurface are, by convention, abbreviated with a single
141  "p" rather than 2, as in pO₂ not ppO₂
142  Where more than one term exists for something, please choose the one already
143  in use within Subsurface e.g. Cylinder vs. Tank.
144
145
146Sample Settings
147===============
148
149Emacs
150-----
151
152These lines in your .emacs file should get you fairly close when it comes
153to indentation - many of the other rules you have to follow manually
154
155;; indentation
156(defun c-lineup-arglist-tabs-only (ignored)
157  "Line up argument lists by tabs, not spaces"
158  (let* ((anchor (c-langelem-pos c-syntactic-element))
159         (column (c-langelem-2nd-pos c-syntactic-element))
160         (offset (- (1+ column) anchor))
161         (steps (floor offset c-basic-offset)))
162    (* (max steps 1)
163       c-basic-offset)))
164
165(add-hook 'c-mode-common-hook
166          (lambda ()
167            ;; Add kernel style
168            (c-add-style
169             "linux-tabs-only"
170             '("linux" (c-offsets-alist
171                        (arglist-cont-nonempty
172                         c-lineup-gcc-asm-reg
173                         c-lineup-arglist-tabs-only))))))
174
175(add-hook 'c-mode-hook
176          (lambda ()
177            (let ((filename (buffer-file-name)))
178              ;; Enable kernel mode for the appropriate files
179                (setq indent-tabs-mode t)
180                (c-set-style "linux-tabs-only"))))
181
182(add-hook 'c++-mode-hook
183          (lambda ()
184            (let ((filename (buffer-file-name)))
185              ;; Enable kernel mode for the appropriate files
186                (setq indent-tabs-mode t)
187                (c-set-style "linux-tabs-only"))))
188
189
190QtCreator
191---------
192
193These settings seem to get indentation right in QtCreator. Making TAB
194always adjust indent makes it hard to add hard tabs before '\' when
195creating continuing lines. Copying a tab with your mouse / ctrl-C and
196inserting it with ctrl-V seems to work around that problem (use Command
197instead of ctrl on your Mac)
198Save this XML code below to a file, open Preferences (or Tools->Options)
199in QtCreator, pick C++ in the left column and then click on Import...
200to open the file you just created. Now you should have a "Subsurface"
201style that you can select which should work well for our coding style.
202
203
204<?xml version="1.0" encoding="UTF-8"?>
205<!DOCTYPE QtCreatorCodeStyle>
206<!-- Written by QtCreator 3.0.0, 2014-02-27T07:52:57. -->
207<qtcreator>
208 <data>
209  <variable>CodeStyleData</variable>
210  <valuemap type="QVariantMap">
211   <value type="bool" key="AlignAssignments">false</value>
212   <value type="bool" key="AutoSpacesForTabs">false</value>
213   <value type="bool" key="BindStarToIdentifier">true</value>
214   <value type="bool" key="BindStarToLeftSpecifier">false</value>
215   <value type="bool" key="BindStarToRightSpecifier">false</value>
216   <value type="bool" key="BindStarToTypeName">false</value>
217   <value type="bool" key="ExtraPaddingForConditionsIfConfusingAlign">false</value>
218   <value type="bool" key="IndentAccessSpecifiers">false</value>
219   <value type="bool" key="IndentBlockBody">true</value>
220   <value type="bool" key="IndentBlockBraces">false</value>
221   <value type="bool" key="IndentBlocksRelativeToSwitchLabels">false</value>
222   <value type="bool" key="IndentClassBraces">false</value>
223   <value type="bool" key="IndentControlFlowRelativeToSwitchLabels">true</value>
224   <value type="bool" key="IndentDeclarationsRelativeToAccessSpecifiers">true</value>
225   <value type="bool" key="IndentEnumBraces">false</value>
226   <value type="bool" key="IndentFunctionBody">true</value>
227   <value type="bool" key="IndentFunctionBraces">false</value>
228   <value type="bool" key="IndentNamespaceBody">false</value>
229   <value type="bool" key="IndentNamespaceBraces">false</value>
230   <value type="int" key="IndentSize">8</value>
231   <value type="bool" key="IndentStatementsRelativeToSwitchLabels">true</value>
232   <value type="bool" key="IndentSwitchLabels">false</value>
233   <value type="int" key="PaddingMode">2</value>
234   <value type="bool" key="SpacesForTabs">false</value>
235   <value type="int" key="TabSize">8</value>
236  </valuemap>
237 </data>
238 <data>
239  <variable>DisplayName</variable>
240  <value type="QString">Subsurface</value>
241 </data>
242</qtcreator>
243
244
245Vim
246---------
247
248As everybody knows vim is a way better editor than emacs and thus needs to be
249in this file too. Put this into your .vimrc and this should produce something
250close to our coding standards.
251
252" Subsurface coding style
253filetype plugin indent on
254filetype detect
255set cindent tabstop=8 shiftwidth=8 cinoptions=l1,:0,(0,g0
256" TODO: extern "C" gets indented
257
258" And some sane defaults, optional, but quite nice
259set nocompatible
260syntax on
261colorscheme default
262set hls
263set is
264
265" The default blue is just impossible to see on a black terminal
266highlight Comment ctermfg=Brown
267
268" clearly point out when someone have trailing spaces
269highlight ExtraWhitespace ctermbg=red guibg=red
270
271" Show trailing whitespace and spaces before a tab:
272match ExtraWhitespace /\s\+$\| \+\ze\t/
Note: See TracBrowser for help on using the repository browser.