killbots/README.codestyle

   1 ==========================
   2  Killbots C++ Style Guide
   3 ==========================
   4
   5 *******************************************************************************
   6  Indentation
   7 *******************************************************************************
   8
   9 Structural indentation is done with tabs. Formatting is done with spaces. All
  10 code having the same nested depth has the same number of tabs. This separates
  11 meaning from presentation.
  12
  13 Tabwidth is a matter of personal preference. If the above is followed source is
  14 tabwidth independent.
  15
  16 Ensure your editor doesn't do automatic conversion from spaces to tabs, as this
  17 will break things.
  18
  19 Labels (public, private, goto, case, etc.) do not get indented.
  20
  21 Empty lines do not get indentation. In fact, no lines should have trailing
  22 whitespace.
  23
  24 If a pair of parentheses span multiple lines, the closing parenthesis should be
  25 indented (with spaces) to appear in the same column as the opening parenthesis.
  26
  27 Examples:
  28 -------------------------------------------------------------------------------
  29 bool Killbots::Engine::cellIsValid( const QPoint & cell ) const
  30 {
  31 ____return ( 0 <= cell.x()
  32 ____.........&& cell.x() < m_rules->columns()
  33 ____.........&& 0 <= cell.y()
  34 ____.........&& cell.y() < m_rules->rows()
  35 ____.......);
  36 }
  37 -------------------------------------------------------------------------------
  38 namespace Killbots
  39 {
  40 ____class RenderPrivate
  41 ____{
  42 ____public:
  43 ________RenderPrivate()
  44 ________..:.m_svgRenderer(),
  45 ________....m_pixmapCache("killbots-cache"),
  46 ________....m_cursors(),
  47 ________....m_hasBeenLoaded( false )
  48 ________{};
  49 -------------------------------------------------------------------------------
  50 ____if ( m_rulesetChanged )
  51 ____{
  52 ________if ( ! m_engine->gameHasStarted() ||
  53 ________.....KMessageBox::questionYesNo( this,
  54 ________.................................i18n("A new ruleset has been selected, but there is already a game in progress."),
  55 ________.................................i18n("Rule Set Changed"),
  56 ________.................................KGuiItem( i18n("Continue Current Game") ),
  57 ________.................................KGuiItem( i18n("Start a New Game") )
  58 ________...............................) == KMessageBox::No
  59 ________...)
  60 ________{
  61 -------------------------------------------------------------------------------
  62
  63
  64 *******************************************************************************
  65  Braces
  66 *******************************************************************************
  67
  68 Opening and closing braces are always on a new line.
  69
  70 For loop or conditional statements, braces can be omitted if the block is a
  71 single-line statement and the conditional fits on a single line. If braces are
  72 used in one block of an if-elseif-else statement, they should be used in the
  73 other blocks even if those blocks are a single line.
  74
  75 Blocks never appear on the same line as the loop/conditional, even if braces
  76 aren't used.
  77
  78 Empty blocks are represented on a single line as '{}'
  79
  80 Examples:
  81 -------------------------------------------------------------------------------
  82 void Killbots::Engine::refreshSpriteMap()
  83 {
  84     m_spriteMap.clear();
  85     foreach( Sprite * bot, m_bots )
  86         m_spriteMap.insert( bot->gridPos(), bot );
  87     foreach( Sprite * junkheap, m_junkheaps )
  88         m_spriteMap.insert( junkheap->gridPos(), junkheap );
  89 }
  90 -------------------------------------------------------------------------------
  91 if ( m_rules->pushableJunkheaps() != Ruleset::None && cellIsValid( nextCell ) )
  92 {
  93     if ( spriteTypeAt( nextCell ) == NoSprite )
  94         return true;
  95     else if ( spriteTypeAt( nextCell ) == Junkheap )
  96         return m_rules->pushableJunkheaps() == Ruleset::Many && canPushJunkheap( m_spriteMap.value( nextCell ), direction );
  97     else
  98         return m_rules->squaskKillsEnabled();
  99 }
 100 else
 101 {
 102     return false;
 103 }
 104 -------------------------------------------------------------------------------
 105 while ( m_rulesetMap.contains( name ) )
 106     name += '_';
 107 -------------------------------------------------------------------------------
 108
 109 *******************************************************************************
 110  Whitespace
 111 *******************************************************************************
 112
 113 Lines should generally be kept to less than 100 characters, but don't make code
 114 uglier just to avoid width.
 115
 116 Two empty lines should be used to separate function definitions.
 117
 118 Within a block, empty lines may be used to break up unrelated lines, but never
 119 more than one.
 120
 121 No space appears between the function name and the opening bracket.
 122
 123 A single space appears between the loop/conditional statement name and the
 124 opening bracket.
 125
 126 Padding spaces appear inside of all parentheses, unless the parentheses are
 127 empty or contain only a string literal.
 128
 129 Binary operators are separated from their operands with a single space. Unary
 130 operators are not.
 131
 132 Pointer and reference symbols have a space on either side.
 133
 134 No padding spaces appear inside angle brackets when using template functions
 135 or classes.
 136
 137 No space appears between a label and the following colon.
 138
 139 No whitespace should appear inside Qt's SIGNAL and SLOT macros.
 140
 141
 142 *******************************************************************************
 143  Indentifiers
 144 *******************************************************************************
 145
 146 All identifiers should use camel case.
 147
 148 Classnames and namespaces begin with uppercase letters. All other identifiers
 149 begin with lowercase letters.
 150
 151 Class data members are prefixed with 'm_', unless they are public KConfigXT
 152 widgets, in which case, they are prefixed with 'kfcg_'.
 153
 154 Indentifiers should favour descriptiveness over brevity. Single letter
 155 variables are acceptable only for iterators or coordinates.
 156
 157 All indentifiers should use American English spelling. (Comments can be in your
 158 choice of English.)
 159
 160 Examples:
 161 -------------------------------------------------------------------------------
 162 namespace Killbots
 163 {
 164     class Ruleset;
 165
 166     class RulesetSelector : public QWidget
 167     {
 168         Q_OBJECT
 169
 170     public: // functions
 171         explicit RulesetSelector( QWidget * parent = 0 );
 172         virtual ~RulesetSelector();
 173
 174     public: // data members
 175         KLineEdit * kcfg_Ruleset;
 176
 177     private: // functions
 178         void findRulesets();
 179
 180     private slots:
 181         void selectionChanged( QString rulesetName );
 182
 183     private: // data members
 184         QListWidget * m_listWidget;
 185         QLabel * m_author;
 186         QLabel * m_authorContact;
 187         QLabel * m_description;
 188         QMap< QString, Ruleset * > m_rulesetMap;
 189     };
 190 }
 191 -------------------------------------------------------------------------------
 192
 193
 194 *******************************************************************************
 195  Comments
 196 *******************************************************************************
 197
 198 Feel free to comment as much as possible.
 199
 200 Comments should describe the purpose of logic or give background details not
 201 obvious from the code. Comments should not describe what the code is doing,
 202 unless the code is extremely dense (in which case the code should probably be
 203 rewritten/refactored anyway).
 204
 205 Comments appear on the line before the code it is commenting on.
 206
 207 Use '/**/' for comments longer than 3 lines.
 208
 209
 210 *******************************************************************************
 211  Class Definitions
 212 *******************************************************************************
 213
 214 Classes should be given simple names and placed inside the Killbots namespace
 215 instead of adding a prefix. (i.e. Killbots::MainWindow instead of
 216 KillbotsMainWindow)
 217
 218 No inline function definitions in the header, even if they are a single
 219 statement. Same goes for constructors.
 220
 221 Define destructors even if they're empty.
 222
 223 Class definitions should be layed out in the following order.
 224   public: // types
 225   public: // functions
 226   public slots:
 227   public: // data members
 228   signals:
 229   protected: // types
 230   protected: // functions
 231   protected slots:
 232   protected: // data members
 233   private: // types
 234   private: // functions
 235   private slots:
 236   private: // data members
 237
 238
 239 *******************************************************************************
 240  Includes
 241 *******************************************************************************
 242
 243 Include guards are of the form NAMESPACE_CLASSNAME_H.
 244
 245 Group includes in the following order with blank lines in between:
 246   File's own header
 247   Killbots headers
 248   KDE headers
 249   Qt headers
 250
 251 Inside of groups, sort includes alphabetically.
 252
 253 Use the "new" style includes with directory names where appropriate
 254
 255 Forward declare whenever possible in headers.
 256
 257 moc includes appear at the bottom of the source file.
 258
 259 Examples:
 260 -------------------------------------------------------------------------------
 261 #ifndef KILLBOTS_RULESETSELECTOR_H
 262 #define KILLBOTS_RULESETSELECTOR_H
 263
 264 class KLineEdit;
 265
 266 #include <QtCore/QMap>
 267 class QLabel;
 268 class QListWidget;
 269 #include <QtGui/QWidget>
 270
 271 namespace Killbots
 272 {
 273     class Ruleset;
 274 -------------------------------------------------------------------------------
 275 #include "rulesetselector.h"
 276
 277 #include "ruleset.h"
 278 #include "settings.h"
 279
 280 #include <KDE/KDebug>
 281 #include <KDE/KDialog>
 282 #include <KDE/KLineEdit>
 283 #include <KDE/KLocalizedString>
 284 #include <KDE/KStandardDirs>
 285
 286 #include <QtGui/QGroupBox>
 287 #include <QtGui/QLabel>
 288 #include <QtGui/QLayout>
 289 #include <QtGui/QListWidget>
 290 #include <QtGui/QScrollArea>
 291 -------------------------------------------------------------------------------
 292
 293
 294 *******************************************************************************
 295  Miscellaneous
 296 *******************************************************************************
 297
 298 It is generally preferred that functions have a single return statement, but
 299 multiple returns statements are exceptable if a single return would make the
 300 code more complicated.
 301
 302 Use the "Q_UNUSED" macro on unused function parameters.
 303
 304 Use "static_cast<>" instead of the C or C++ style type casts when casting
 305 pointers.
 306
 307 When converting one type to another use C++ or constructor style casts. For
 308 example, use "int()" to convert floating types to integers.
 309
 310 Make sure code passes all the English Breakfast Network checks.