HACKING 5.53 KB
Newer Older
1 2 3 4 5 6 7 8
Since I tend to be one of the more pedantic people on coding style I'll provide
a bit of a reference here.  Please take a few minutes to read this as it will
save us both time when processing patches.

================================================================================
Indentation
================================================================================

9 10
Older versions of JuK had two different indenting schemes.  Now all JuK source
code files simply use 4 spaces at all levels.  In most cases the style of the
11 12 13 14 15
file currently being worked in should be followed.  So:

static void foo()
{
    if(bar()) // <-- 4 spaces
16
        baz() // <-- 8 spaces
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 70 71 72 73 74 75 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
}

================================================================================
Braces
================================================================================

Braces opening classes, structs, namespaces and functions should be on their own
line.  Braces opening conditionals should be on the same line with one notable
exception:  if the conditional is split up onto several lines then the opening
brace should be on its own line.  i.e.

class Foo
{
    // stuff
};

if(foo == bar) {
    // stuff
}

while(foo == bar &&
      baz == quux &&
      flop == pop)
{
    // stuff
}

static void foo()
{
    // stuff
}

Other exceptions include inline functions that are just returning or setting a
value.  However multiple statements should not ever be combined onto one line:

class Foo
{
public:
    String value() const { return m_value; }
};

Also conditionals / loops that only contiain one line in their body (but where
the conditional statement fits onto one line) should omit braces:

if(foo == bar)
    baz();

But:

if(baz == quux &&
   ralf == spot)
{
    bar();
}

================================================================================
Spaces
================================================================================

Spaces should not be used between the conditional / loop type and the
conditional statement.  They should also not be used after parenthesis.  However
the should be to mark of mathematical or comparative operators.

if ( foo == bar )
  ^ ^          ^

The marked spaces should be ommitted to produce:

if(foo == bar)

================================================================================
Header Organization
================================================================================

Member variables should always be private and prefixed with "m_".  Accessors may
be inline in the headers.  The organization of the members in a class should be
roughly as follows:

public:
public slots:
protected:
protected slots:
signals:
private: // member funtions
private slots:
private: // member variables

If there are no private slots there is no need for two private sections, however
private functions and private variables should be clearly separated.

The implementations files -- .cpp files -- should follow (when possible) the
same order of function declarations as the header files.

Virtual functions should always be marked as such even in derrived classes where
it is not strictly necessary.

================================================================================
Whitespace
================================================================================

Whitespace should be used liberally.  When blocks of code are logically distinct
I tend to put a blank line between them.  This is difficult to explain
systematically but after looking a bit at the current code organization this
ideally will be somewhat clear.

Also I tend to separate comments by blank lines on both sides.

================================================================================
Pointer and Reference Operators
================================================================================

This one is pretty simple.  I prefer "Foo *f" to "Foo* f" in function signatures
and declarations.  The same goes for "Foo &f" over "Foo& f".

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
================================================================================
Editor Support
================================================================================

Most JuK files that Michael Pyne has touched will eventually have a vim modeline
at the bottom of the file (after any moc #includes).  The current vim modeline
is the following:

// vim: set et sw=4 tw=0 sta:

The vim: ... : part encloses the commands to automatically use when opening the
file in vim.  The following commands are set:
  et     : Uses spaces instead of the <TAB> when the Tab key is pressed.  No
           JuK source should have tab characters anymore, this helps enforce
	   that.  Full name is expandtab.
  sw = 4 : Makes indenting levels 4 spaces wide, for use with the vim indenting
           features.  Full name is shiftwidth.
  tw = 0 : Prevents vim from wrapping lines as you are typing.  Full name is
           textwidth.
  sta    : Use shiftwidth to determine tab size at the beginning of the line,
           instead of tabstop (which is normally 8 spaces wide).  Full name is
	   smarttab.

Also, vim users will want to have the command "let c_space_errors=1" in their
.vimrc in order to flag extra whitespace at the end of lines, which is also a
no-no in source code.

There are vim and emacs scripts for KDE developers in kdesdk/scripts, you may
also want to see what is available there.

161 162 163 164 165 166 167
================================================================================

There are likely things missing here and I'll try to add them over time as I
notice things that are often missed.  Please let me know if specific points are
ambiguous.

Scott Wheeler <wheeler@kde.org>