Warning, /multimedia/subtitlecomposer/README.CodingStyle.md is written in an unsupported language. File is not indexed.
0001 ## SubtitleComposer Coding Style ## 0002 0003 ### Indentation 0004 0005 1 tab is used for indentation 0006 0007 Tab, not spaces! 0008 0009 0010 ### Declaring variables 0011 0012 Declare each variable on a separate line 0013 0014 Avoid short or meaningless names (e.g. "a", "rbarr", "nughdeget") 0015 0016 Single character variable names are only okay for counters and temporaries, where the purpose of the variable is obvious 0017 0018 Wait when declaring a variable until it is needed 0019 0020 ```C++ 0021 // Wrong 0022 int a, b; 0023 char *c, *d; 0024 0025 // Correct 0026 int height; 0027 int width; 0028 char *nameOfThis; 0029 char *nameOfThat; 0030 ``` 0031 0032 Variables and functions start with a lower-case letter. Each consecutive word in a variable’s name starts with an upper-case letter 0033 0034 Avoid abbreviations 0035 0036 ```C++ 0037 // Wrong 0038 short Cntr; 0039 char ITEM_DELIM = '\t'; 0040 0041 // Correct 0042 short counter; 0043 char itemDelimiter = '\t'; 0044 ``` 0045 0046 Classes always start with an upper-case letter. Public classes start with a ‘Q’ (QRgb) followed by an upper case letter. Public functions most often start with a ‘q’ (qRgb). 0047 Acronyms are camel-cased (e.g. QXmlStreamReader, not QXMLStreamReader). 0048 0049 0050 ### Whitespace 0051 0052 Use blank lines to group statements together where suited 0053 Always use only one blank line 0054 Do not use space after a keyword 0055 Always use one single space before a curly brace: 0056 0057 ```C++ 0058 // Wrong 0059 if (foo){ 0060 } 0061 0062 // Correct 0063 if(foo) { 0064 } 0065 ``` 0066 0067 For pointers or references, always use a single space between the type and ‘*’ or ‘&’, but no space between the ‘*’ or ‘&’ and the variable name: 0068 0069 ```C++ 0070 // Correct 0071 char *x; 0072 const QString &myString; 0073 const char * const y = "hello"; 0074 ``` 0075 0076 Surround binary operators with spaces 0077 No space after a cast 0078 Avoid C-style casts when possible 0079 0080 ```C++ 0081 // Wrong 0082 char* blockOfMemory = (char*)malloc(data.size()); 0083 0084 // Correct 0085 char *blockOfMemory = reinterpret_cast<char *>(malloc(data.size())); 0086 ``` 0087 0088 Do not put multiple statements on one line 0089 By extension, use a new line for the body of a control flow statement: 0090 0091 ```C++ 0092 // Wrong 0093 if(foo) bar(); 0094 0095 // Correct 0096 if(foo) 0097 bar(); 0098 ``` 0099 0100 0101 ### Braces 0102 0103 Use attached braces: The opening brace goes on the same line as the start of the statement. If the closing brace is followed by another keyword, it goes into the same line as well: 0104 0105 ```C++ 0106 // Wrong 0107 if(codec) 0108 { 0109 } 0110 else 0111 { 0112 } 0113 0114 // Correct 0115 if(codec) { 0116 } else { 0117 } 0118 ``` 0119 0120 Exception: Function implementations and class declarations always have the left brace on the start of a line: 0121 0122 ```C++ 0123 // Correct 0124 static void 0125 foo(int g) 0126 { 0127 qDebug("foo: %i", g); 0128 } 0129 0130 class Moo 0131 { 0132 }; 0133 ``` 0134 0135 Use curly braces only when the body of a conditional statement contains more than one line: 0136 0137 ```C++ 0138 // Wrong 0139 if(address.isEmpty()) { 0140 return false; 0141 } 0142 0143 for(int i = 0; i < 10; ++i) { 0144 qDebug("%i", i); 0145 } 0146 0147 // Correct 0148 if(address.isEmpty()) 0149 return false; 0150 0151 for(int i = 0; i < 10; ++i) 0152 qDebug("%i", i); 0153 ``` 0154 0155 Exception 1: Use braces also if the parent statement covers several lines / wraps: 0156 0157 ```C++ 0158 // Correct 0159 if(address.isEmpty() || !isValid() 0160 || !codec) { 0161 return false; 0162 } 0163 ``` 0164 0165 Exception 2: Brace symmetry: Use braces also in if-then-else blocks where either the if-code or the else-code covers several lines: 0166 0167 ```C++ 0168 // Wrong 0169 if(address.isEmpty()) 0170 return false; 0171 else { 0172 qDebug("%s", qPrintable(address)); 0173 ++it; 0174 } 0175 0176 // Correct 0177 if(address.isEmpty()) { 0178 return false; 0179 } else { 0180 qDebug("%s", qPrintable(address)); 0181 ++it; 0182 } 0183 0184 // Wrong 0185 if(a) 0186 if(b) 0187 ... 0188 else 0189 ... 0190 // Correct 0191 if(a) { 0192 if(b) 0193 ... 0194 else 0195 ... 0196 } 0197 ``` 0198 0199 Use curly braces when the body of a conditional statement is empty 0200 0201 ```C++ 0202 // Wrong 0203 while(a); 0204 0205 // Correct 0206 while(a) {} 0207 ``` 0208 0209 0210 ### Parentheses 0211 0212 Use parentheses to group expressions: 0213 0214 ```C++ 0215 // Wrong 0216 if(a && b || c) 0217 0218 // Correct 0219 if((a && b) || c) 0220 0221 // Wrong 0222 a + b & c 0223 0224 // Correct 0225 (a + b) & c 0226 ``` 0227 0228 0229 ### Switch statements 0230 0231 The case labels are in the same column as the switch 0232 Every case must have a break (or return) statement at the end or a comment to indicate that there’s intentionally no break, unless another case follows immediately. 0233 0234 ```C++ 0235 // Correct 0236 switch(myEnum) { 0237 case Value1: 0238 doSomething(); 0239 break; 0240 case Value2: 0241 case Value3: 0242 doSomethingElse(); 0243 // fall through 0244 default: 0245 defaultHandling(); 0246 break; 0247 } 0248 ``` 0249 0250 Jump statements (break, continue, return, and goto) 0251 0252 Do not put ‘else’ after jump statements: 0253 0254 ```C++ 0255 // Wrong 0256 if(thisOrThat) 0257 return; 0258 else 0259 somethingElse(); 0260 0261 // Correct 0262 if(thisOrThat) 0263 return; 0264 somethingElse(); 0265 ``` 0266 0267 Exception: If the code is inherently symmetrical, use of ‘else’ is allowed to visualize that symmetry 0268 0269 0270 ### Line breaks 0271 0272 Keep lines shorter than 100 characters; wrap if necessary 0273 Commas go at the end of wrapped lines; operators start at the beginning of the new lines. An operator at the end of the line is easy to miss if the editor is too narrow. 0274 0275 ```C++ 0276 // Wrong 0277 if(longExpression + 0278 otherLongExpression + 0279 otherOtherLongExpression) { 0280 } 0281 0282 // Correct 0283 if(longExpression 0284 + otherLongExpression 0285 + otherOtherLongExpression) { 0286 } 0287 ``` 0288 0289 0290 ### Inheritance and the `virtual` keyword 0291 0292 When reimplementing a virtual method, do not put the `virtual` keyword in the header file. 0293 On Qt5, annotate them with the [Q_DECL_OVERRIDE](http://qt-project.org/doc/qt-5.0/qtcore/qtglobal.html#Q_DECL_OVERRIDE) macro after the function declaration, just before the ‘;’ (or the ‘{’ ). 0294 0295 0296 ### Qt Includes 0297 0298 Do not use both the module and class name for Qt includes. 0299 0300 ```C++ 0301 // Correct 0302 #include <QString> 0303 0304 // Wrong 0305 #include <QtCore/QString> 0306 ``` 0307 0308 0309 ### C++11 Lambdas 0310 0311 You can use lambdas with the following restrictions: 0312 0313 * You have to explicitly specify the return type (unless it's void), if the lambda contains more than a single expression. 0314 0315 ```C++ 0316 // Correct 0317 []() -> QString { 0318 Foo *foo = activeFoo(); 0319 return foo ? foo->displayName() : QString(); 0320 }); 0321 0322 // Wrong 0323 []() { 0324 Foo *foo = activeFoo(); 0325 return foo ? foo->displayName() : QString(); 0326 }); 0327 ``` 0328 0329 * If you use static functions from the class that the lambda is located in, you have to explicitly capture this. Otherwise it does not compile with g++ 4.7 and earlier. 0330 ```C++ 0331 // Correct 0332 void 0333 Foo::something() 0334 { 0335 ... 0336 [this]() { Foo::someStaticFunction(); } 0337 ... 0338 } 0339 0340 // Wrong 0341 void 0342 Foo::something() 0343 { 0344 ... 0345 []() { Foo::someStaticFunction(); } 0346 ... 0347 } 0348 ``` 0349 0350 Format the lambda according to the following rules: 0351 0352 * Always write parentheses for the parameter list, even if the function does not take parameters. 0353 0354 ```C++ 0355 // Correct 0356 []() { doSomething(); } 0357 0358 // Wrong 0359 [] { doSomething(); } 0360 ``` 0361 0362 * Place the capture-list, parameter list, return type, and opening brace on the first line, the body indented on the following lines, and the closing brace on a new line. 0363 ```C++ 0364 // Correct 0365 []() -> bool { 0366 something(); 0367 return isSomethingElse(); 0368 } 0369 0370 // Wrong 0371 []() -> bool { something(); 0372 somethingElse(); } 0373 ``` 0374 0375 * Place a closing parenthesis and semicolon of an enclosing function call on the same line as the closing brace of the lambda. 0376 ```C++ 0377 // Correct 0378 foo([]() { 0379 something(); 0380 }); 0381 ``` 0382 0383 * If you are using a lambda in an 'if' statement, start the lambda on a new line, to avoid confusion between the opening brace for the lambda and the opening brace for the 'if' statement. 0384 ```C++ 0385 // Correct 0386 if(anyOf(fooList, 0387 [](Foo foo) { 0388 return foo.isGreat(); 0389 }) { 0390 return; 0391 } 0392 0393 // Correct - place the lambda completely on one line if it fits 0394 if(foo([]() { return true; })) { 0395 ... 0396 } 0397 0398 // Wrong 0399 if(anyOf(fooList, [](Foo foo) { 0400 return foo.isGreat(); 0401 }) { 0402 return; 0403 } 0404 ``` 0405 0406 0407 ### C++11 auto keyword 0408 0409 You can use the auto keyword in the following cases. If in doubt (e.g. using auto could make the code less readable) do not use auto. Keep in mind that code is read much more often than written. 0410 0411 * When it avoids repetition of a type in the same statement. 0412 ```C++ 0413 // Correct 0414 auto something = new MyCustomType; 0415 auto keyEvent = static_cast<QKeyEvent *>(event); 0416 ``` 0417 0418 * When assigning iterator types. 0419 ```C++ 0420 // Correct 0421 auto it = myList.const_iterator(); 0422 ``` 0423 0424 ### C++11 initializer lists 0425 0426 You should prefer initializer lists over adding the entries at runtime. 0427 0428 ```C++ 0429 // Wrong 0430 auto myList = QStringList() << QLatin1String("FooThing") << QLatin1String("BarThing"); 0431 // Correct 0432 QStringList myList{QStringLiteral("FooThing"), QStringLiteral("BarThing")}; 0433 QStringList myListWithSingleEntry{QStringLiteral("FooThing")}; 0434 ``` 0435 0436 ### General exception 0437 0438 When strictly following a rule makes your code look bad, feel free to break it