HACKING 8.54 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
Hacking on VLMC
---------------

Thanks
------
Most parts of this guide are taken from the Amarok coding rules.

This C++ FAQ is a life saver in many situations, so you want to keep it handy:

  http://www.parashift.com/c++-faq-lite/


Formatting
----------
* Spaces, not tabs
* Indentation is 4 spaces
* No trailing spaces
* Lines should be limited to 90 characters
* Spaces between brackets and argument functions
* Spaces before and after operators
* For pointer and reference variable declarations put a space between the type
  and the * or & and no space before the variable name.
* For if, else, while and similar statements put the brackets on the next line,
  although brackets are not needed for single statements.
* Function and class definitions have their brackets on separate lines
* A function implementation's return type is on its own line.
* A return keyword must be used without parenthesis.
* CamelCase.{cpp,h} style file names.
* Qt 4 includes a foreach keyword which makes it very easy to iterate over all
  elements of a container.

Example:

 | bool
 | MyClass::myMethod( QStringList list, const QString &name )
 | {
 |     if( list.isEmpty() )
 |         return false;
 |
 |     /*
 |       Define the temporary variable like this to restrict its scope
 |       when you do not need it outside the loop. Let the compiler
 |       optimise it.
 |     */
 |     foreach( const QString &string, list )
 |         debug() << "Current string is " << string;
 | }


The program astyle can be used to automatically format source code, which can
be useful for badly formatted 3rd party patches.

Use it like this to get (approximately) VLMC formatting style:

    "astyle -s4 -b -p -U -D -o source.cpp"


Class, Function, Enums & Variable Naming
---------------------------------
* Use CamelCase for everything.
* Local variables should start out with a lowercase letter.
* Class names are capitalized
* Prefix class member variables with m_, ex. m_tracksView.
* Prefix static member variables with s_, ex s_instance
* Functions are named in the Qt style. It's like Java's, without the "get"
  prefix.
  * A getter is variable()
  * If it's a getter for a boolean, prefix with 'is', so isCondition()
  * A setter is setVariable( arg ).
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
70
* Variable declaration must contain indentation between type and variable name
71

Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
72 73 74 75
Good:
 | MyType       *ptr;
Wrong:
 | MyType *ptr;
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214

Best Practices
--------------
* Focus on code portability
* Focus on code readability
  * Do not overload an operator without a valid justification
  * For each overloaded operator, there must be an equivalent method
  * Do not use reinterpret_cast without a valid justification
  * Do not write functions and/or methods of more than 100 lines


Includes
--------
Header includes should be listed in the following order:
    - Own Header
    - VLMC includes
    - Qt includes

They should also be sorted alphabetically, for ease of locating them. A small
comment if applicable is also helpful.

Includes in a header file should be kept to the absolute minimum, as to keep
compile times low. This can be achieved by using "forward declarations"
instead of includes, like "class QListView;". Forward declarations work for
pointers and const references.

In vim you can sort headers automatically by marking the block, and then
doing ":sort".

Example:

 | #include "MySuperWidget.h"
 |
 | #include "Timeline.h"
 | #include "TracksRuler.h"
 | #include "TracksView.h"
 |
 | #include <QGraphicsView>
 | #include <QWidget>


Comments
--------
Comment your code. Don't comment what the code does, comment on the purpose of
the code. It's good for others reading your code, and ultimately it's good for
you too. Every method must be commented (in Doxygen format), including
potential return value and potential parameters.

For headers, use the Doxygen syntax. See: http://www.stack.nl/~dimitri/doxygen/


Header Formatting
-----------------
General rules apply here. Please keep header function definitions aligned
nicely, if possible. It helps greatly when looking through the code. Sorted
methods, either by name or by their function (ie, group all related methods
together) is great too. Access levels should be sorted in this order:
public, protected, private.

Example:

 | #ifndef TRACKSCONTROLS_H
 | #define TRACKSCONTROLS_H
 |
 | class TracksControls : public QScrollArea
 | {
 |     Q_OBJECT
 |
 |     public:
 |         TracksControls( QWidget *parent = 0 );
 |         ~TracksControls() {};
 |
 |     public slots:
 |         void            addVideoTrack( GraphicsTrack *track );
 |         void            addAudioTrack( GraphicsTrack *track );
 |         void            clear();
 |
 |     private:
 |         QWidget         *m_centralWidget;
 |         QWidget         *m_separator;
 |         QVBoxLayout     *m_layout;
 | };
 |
 | #endif // TRACKSCONTROLS_H


0 vs NULL
---------
0 and NULL are the same in C++. However, NULL is expected to be used with
pointers, therefore, it improves code clarity.
To summarize:
 * You shall use NULL when dealing with pointers.
 * You must not use NULL when dealing with something that's not a pointer.


Const Correctness
-----------------
Try to keep your code const correct. Declare methods const if they don't mutate
the object, and use const variables. It improves safety, and also makes it
easier to understand the code.

In case of a pointer/reference to a const value, you must put the const at the
beginning of the line.

See: http://www.parashift.com/c++-faq-lite/const-correctness.html

Example:

 | bool
 | MyClass::isValidFile( const QString &path ) const
 | {
 |     const bool valid = QFile::exist( path );
 |
 |     return valid;
 | }


Casts
-----
Prefer C++ casts instead of the traditionnals C casts.

Wrong:
 | void
 | MyClass::clicked( QAbstractButton *button )
 | {
 |     QPushButton *pButton = (QPushButton*)button;
 |
 |     pButton->setFlat( true );
 | }

Correct:
 | void
 | MyClass::clicked( QAbstractButton *button )
 | {
 |     QPushButton *pButton = static_cast<QPushButton *>( button );
 |
 |     pButton->setFlat( true );
 | }

Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
215 216 217 218 219 220 221 222 223 224 225 226 227 228
Moreover, try to use Qt's cast when applicable :
 | MyParentClass    *ptr;
 | MyClass          *ptr2 = qobject_cast<MyClass*>( ptr );
 | if ( ptr2 != NULL )
 | {
 | ...
 | }
Is much faster than
 | MyParentClass    *ptr;
 | MyClass          *ptr2 = dynamic_cast<MyClass*>( ptr );
 | if ( ptr2 != NULL )
 | {
 | ...
 | }
229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282

Commenting Out Code
-------------------
Don't keep commented out code. It just causes confusion and makes the source
harder to read. Remember, the last revision before your change is always
availabe in Git. Hence no need for leaving cruft in the source.

Wrong:
 | myWidget->show();
 | //myWidget->rise(); //what is this good for?

Correct:
 | myWidget->show();


Internationalization (i18n)
---------------------------
Each translatable string should be enclosed within a tr().

Wrong:
 | myPushButton->setText( "Click me!" );

Correct:
 | myPushButton->setText( tr( "Click me!" ) );

Read more on: http://doc.trolltech.com/i18n-source-translation.html

VLMC also supports retranslation of the entire GUI at runtime. You should
subscribe to QEvent::LanguageChange to be notified of a language change and
update the GUI accordingly.

Example:

 | void
 | MyWidget::changeEvent( QEvent *e )
 | {
 |     QFrame::changeEvent( e );
 |     switch( e->type() )
 |     {
 |     case QEvent::LanguageChange:
 |         ui.retranslateUi( this );
 |         break;
 |     default:
 |         break;
 |     }
 | }


Embedding UI Class
------------------
Use simple aggregation to embed a Qt UI into your class.

Example:

283
 | #include "ui/MyWidget.h"
284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
 |
 | class MyWidget : public QFrame
 | {
 |     Q_OBJECT
 |
 |     public:
 |         MyWidget( QWidget *parent = 0 );
 |         ~MyWidget() {};
 |
 |     protected:
 |         virtual void changeEvent( QEvent *e );
 |
 |     private:
 |         Ui::MyWidget ui;
 | };


Debugging
---------
Debug is not printed out on the console by default. However, everything is
written to a log file. This can be changed by setting -v, -vv, and
--logfile=[output_file]

Don't ever ever ever let some debugs such as "i am here", "ptr == 0xDEADB33F".
Just let what's required. (ie: a media loaded, the render has started.... )


Copyright
---------
To comply with the GPL, add your name, email address & the year to the top of
any file that you edit. If you bring in code or files from elsewhere, make sure
its GPL-compatible and to put the authors name, email & copyright year to the
top of those files.

Please note that it is not sufficient to write a pointer to the license (like a
URL). The complete license header needs to be written everytime.

Thanks, now have fun!
  -- the VLMC developers
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
323