Warning, /multimedia/dragon/HACKING is written in an unsupported language. File is not indexed.

0001 Dragon Video Player is a sister project to Amarok, its HACKING guidelines are the 
0002 same with minimal exception.
0003 
0004 Hacking on Amarok
0005 -----------------
0006 
0007 Please respect these guidelines when coding for Amarok, thanks!
0008 
0009 * Where this document isn't clear, refer to Amarok code.
0010 
0011 
0012 This C++ FAQ is a life saver in many situations, so you want to keep it handy:
0013 
0014   http://www.parashift.com/c++-faq-lite/
0015 
0016 
0017 Formatting
0018 ----------
0019 * Spaces, not tabs
0020 * Indentation is 4 spaces
0021 * Lines should be limited to 90 characters
0022 * Spaces between brackets and argument functions
0023 * For pointer and reference variable declarations put a space between the type
0024   and the * or & and no space before the variable name.
0025 * For if, else, while and similar statements put the brackets on the next line,
0026   although brackets are not needed for single statements.
0027 * Function and class definitions have their brackets on separate lines
0028 * A function implementation's return type is on its own line.
0029 * camelCase.{cpp,h} style file names.
0030 * Qt 4 includes a foreach keyword which makes it very easy to iterate over all
0031   elements of a container.
0032 
0033 Example:
0034 
0035  | bool 
0036  | MyClass::myMethod( QStringList list, const QString &name )
0037  | {
0038  |     if( list.isEmpty() )
0039  |         return false;
0040  |
0041  |     /*
0042  |       Define the temporary variable like this to restrict its scope
0043  |       when you do not need it outside the loop. Let the compiler
0044  |       optimise it.
0045  |      */
0046  |     foreach( const QString &string, list )
0047  |     {
0048  |
0049  |         debug() << "Current string is " << string << endl;
0050  |     }
0051  | }
0052 
0053 Header includes should be listed in the following order:
0054     - Amarok includes
0055     - KDE includes
0056     - Qt includes
0057 
0058 They should also be sorted alphabetically, for ease of locating them.  A small comment
0059 if applicable is also helpful.
0060 
0061 Includes in a header file should be kept to the absolute minimum, as to keep compile times
0062 low. This can be achieved by using "forward declarations" instead of includes, like
0063 "class QListView;" Forward declarations work for pointers and const references.
0064 
0065 TIP:
0066 Kate/KDevelop users can sort the headers automatically. Select the lines you want to sort,
0067 then Tools -> Filter Selection Through Command -> "sort".
0068 
0069 
0070 Example:
0071 
0072  | #include "amarok.h"
0073  | #include "debug.h"
0074  | #include "playlist.h"
0075  |
0076  | #include <KDialogBase>    //baseclass
0077  | #include <KPushButton>    //see function...
0078  |
0079  | #include <QGraphicsView>
0080  | #include <QWidget>
0081 
0082 
0083 Comments
0084 --------
0085 Comment your code. Don't comment what the code does, comment on the purpose of the code. It's
0086 good for others reading your code, and ultimately it's good for you too.
0087 
0088 Comments are essential when adding a strange hack, like the following example:
0089 
0090  | /** Due to xine-lib, we have to make K3Process close all fds, otherwise we get "device is busy" messages
0091  |   * Used by AmarokProcIO and AmarokProcess, exploiting commSetupDoneC(), a virtual method that
0092  |   * happens to be called in the forked process
0093  |   * See bug #103750 for more information.
0094  |   */
0095  | class AmarokProcIO : public K3ProcIO 
0096  | {
0097  |     public:
0098  |     virtual int commSetupDoneC() {
0099  |         const int i = K3ProcIO::commSetupDoneC();
0100  |         Amarok::closeOpenFiles(K3ProcIO::out[0],K3ProcIO::in[0],K3ProcIO::err[0]);
0101  |         return i;
0102  |     }
0103  | };
0104 
0105 
0106 For headers, use the Doxygen syntax. See: http://www.stack.nl/~dimitri/doxygen/
0107 
0108 Example:
0109 
0110  | /**
0111  |  * Start playback.
0112  |  * @param offset Start playing at @p msec position.
0113  |  * @return True for success.
0114  |  */
0115  | virtual bool play( uint offset = 0 ) = 0;
0116 
0117 
0118 Header Formatting
0119 -----------------
0120 General rules apply here.  Please keep header function definitions aligned nicely,
0121 if possible.  It helps greatly when looking through the code.  Sorted methods,
0122 either by name or by their function (ie, group all related methods together) is
0123 great too.
0124 
0125 
0126  | #ifndef AMAROK_QUEUEMANAGER_H
0127  | #define AMAROK_QUEUEMANAGER_H
0128 
0129  | class QueueList : public K3ListView
0130  | {
0131  |         Q_OBJECT
0132  |
0133  |     public:
0134  |         Queuelist( QWidget *parent, const char *name = 0 );
0135  |         ~QueueList() {};
0136  |
0137  |     public slots:
0138  |         void    moveSelectedUp();
0139  |         void    moveSelectedDown();
0140  | };
0141 
0142 #endif /* AMAROK_QUEUEMANAGER_H */
0143 
0144 
0145 0 vs NULL
0146 ---------
0147 The use of 0 to express a null pointer is preferred over the use of NULL.
0148 0 is not a magic value, it's the defined value of the null pointer in C++.
0149 NULL, on the other hand, is a preprocessor directive (#define) and not only is
0150 it more typing than '0' but preprocessor directives are less elegant.
0151 
0152  |     SomeClass *instance = 0;
0153 
0154 
0155 Const Correctness
0156 -----------------
0157 Try to keep your code const correct. Declare methods const if they don't mutate the object,
0158 and use const variables. It improves safety, and also makes it easier to understand the code.
0159 
0160 See: http://www.parashift.com/c++-faq-lite/const-correctness.html
0161 
0162 
0163 Example:
0164 
0165  | bool 
0166  | MyClass::isValidFile( const QString& path ) const
0167  | {
0168  |     const bool valid = QFile::exist( path );
0169  |
0170  |     return valid;
0171  | }
0172 
0173 
0174 Debugging
0175 ---------
0176 debug.h contains some handy functions for our debug console output.
0177 Please use them instead of kDebug().
0178 
0179 Usage:
0180 
0181  | #include "debug.h"
0182  |
0183  | debug()   << "Something is happening" << endl;
0184  | warning() << "Something bad may happen" << endl;
0185  | error()   << "Something bad did happen!" << endl;
0186 
0187 Additionally, there are some macros for debugging functions:
0188 
0189 DEBUG_BLOCK
0190 DEBUG_FUNC_INFO
0191 DEBUG_LINE_INFO
0192 DEBUG_INDENT
0193 DEBUG_UNINDENT
0194 
0195 AMAROK_NOTIMPLEMENTED
0196 AMAROK_DEPRECATED
0197 
0198 threadweaver.h has two additional macros:
0199 DEBUG_THREAD_FUNC_INFO outputs the memory address of the current QThread or 'none'
0200     if its the original GUI thread.
0201 SHOULD_BE_GUI outputs a warning message if it occurs in a thread that isn't in
0202     the original "GUI Thread", otherwise it is silent. Useful for documenting
0203     functions and to prevent problems in the future.
0204 
0205 
0206 Usage of Amarok::config()
0207 -------------------------
0208 We provide this method for convenience, but it is important to use it properly. By
0209 inspection, we can see that we may produce very obscure bugs in the wrong case:
0210 
0211  | KConfig 
0212  | *config( const QString &group )
0213  | {
0214  |    //Slightly more useful config() that allows setting the group simultaneously
0215  |    KGlobal::config()->setGroup( group );
0216  |    return KGlobal::config();
0217  | }
0218 
0219 Take the following example:
0220  
0221  | void
0222  | f1()
0223  | {
0224  |    KConfig *config = Amarok::config( "Group 2" );
0225  |    config->writeEntry( "Group 2 Variable", true );
0226  | }
0227  |
0228  | void
0229  | doStuff()
0230  | {
0231  |   KConfig *config = Amarok::config( "Group 1" );
0232  |   f1();
0233  |   config->writeEntry( "Group 1 Variable", true );
0234  | }
0235 
0236 We would expect the following results:
0237 
0238  | [Group 1]
0239  | Group 1 Variable = true
0240  |
0241  | [Group 2]
0242  | Group 2 Variable = true
0243 
0244 However because the config group is changed before writing the entry:
0245  | [Group 1]
0246  |
0247  | [Group 2]
0248  | Group 1 Variable = true
0249  | Group 2 Variable = true
0250 
0251 Which is clearly incorrect. And hard to see when your wondering why f1() is not
0252 working. So do not store a value of Amarok::config, make it a habit to just 
0253 always call writeEntry or readEntry directly.
0254 
0255 Correct:
0256  | amarok::config( "Group 1" )->writeEntry( "Group 1 Variable", true );
0257 
0258 
0259 Errors & Asserts
0260 ----------------
0261 *Never use assert() or fatal(). There must be a better option than crashing a user's
0262 application (its not uncommon for end-users to have debugging enabled).
0263 
0264 *KMessageBox is fine to use to prompt the user, but do not use it to display errors
0265 or informational messages. Instead, KDE::StatusBar has a few handy methods. Refer to
0266 amarok/src/statusbar/statusBarBase.h
0267 
0268 
0269 Commenting Out Code
0270 -------------------
0271 Don't keep commented out code. It just causes confusion and makes the source
0272 harder to read. Remember, the last revision before your change is always
0273 availabe in SVN. Hence no need for leaving cruft in the source.
0274 
0275 Wrong:
0276  | myWidget->show();
0277  | //myWidget->rise(); //what is this good for?
0278 
0279 Correct:
0280  | myWidget->show();
0281 
0282 
0283 Tips & Tricks
0284 -------------
0285 A useful service is http://lxr.kde.org. Lxr is a cross reference of the entire
0286 KDE SVN repository. You can for instance use it to search for example code
0287 from other applications for a given KDElibs method.
0288 
0289 
0290 Copyright
0291 ---------
0292 To comply with the GPL, add your name, email address & the year to the top of any file
0293 that you edit. If you bring in code or files from elsewhere, make sure its
0294 GPL-compatible and to put the authors name, email & copyright year to the top of
0295 those files.
0296 
0297 Please note that it is not sufficient to write a pointer to the license (like a URL).
0298 The complete license header needs to be written everytime.
0299 
0300 
0301 Thanks, now have fun!
0302   -- the Amarok developers