The unofficial coding best practise and code formatting conventions for XBMC

  Thread Rating:
  • 0 Votes - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Post Reply
jmarshall Offline
Team-XBMC Developer
Posts: 25,689
Joined: Oct 2003
Reputation: 169
Information  The unofficial coding best practise and code formatting conventions for XBMC
Post: #1
There are some development notes and developing guidelines in the wiki like;
...but all those does not go down to the code level with info on the preferred;
  • Coding guidelines
  • Commenting guidelines
  • Include guidelines
  • Filename guidelines
  • Review guidelines

So lets discuss that here in this thread:

If there is a firmly established guideline in place, it will help the coding by multiple developers to go much smoother. Also, all developers (coders in particular) should be subscribed to the SVN mailing list and there should be a policy of encouraging review of the code by each other (with reference to the coding guidelines as needed).

The current code in places is a bit messy as far as layout goes, so here's an attempt at getting a format that we can all pseudo agree on to help us keep things readable. i've taken most of this from the scummvm code conventions, and altered it with my personal preferences (well, i did have to format all this Tongue )

XBMC Code Formatting Conventions

1. use common sense

these are conventions which we try to follow when writing code for xboxmediacenter. they are this way mainly for reasons of taste, however, sticking to a common set of formatting rules also makes it slightly easier to read through our sources. if you want to submit patches, please try to follow these rules.

as such we don't follow these rules slavishly, in certain cases it is ok (and in fact favorable) to stray from them.

2. braces

braces in your code should look like the following example:
Quote:if (int i = 0; i < t; i++)
{
[...]
}
else
{
[...]
}

class dummy()
{
[...]
}

3. indents, at two spaces, using spaces.
in msdev, the settings should be setup as follows:
[Image: msdev_options.jpg]

4. whitespace

1. conventional operators surrounded by a space character
Quote:a = (b + c) * d;

2. c++ reserved words separated from opening parentheses by a white space

Quote:while (true)


3. commas followed by a white space

Quote:somefunction(a, b, c);
int d, e;


4. semicolons followed by a space character, if there is more on line

Quote:for (int a = 0; b++; c < d)
dosomething(e); dosomething(f); // this is probably bad style anyway


5. when declaring class inheritance and in a ? construct, colons should be surrounded by white space

Quote:class buswheel : public rubberinflatable
(isnight) ? colormedark() : colormebright();


5. switch / case constructs

Code:
switch (cmd)
{
case ksavecmd:
  save();
  break;
case kloadcmd:
case kplaycmd:
  close();
  break;
default:
  dialog::handlecommand(sender, cmd, data);
}

6. naming

1. constants - use caps with underscore spacing where necessary.
Quote:const int SOME_KLUDGY_CONSTANT_NAME = 1;

2. variables - only rule is that they are obviously named. hovering in msdevstudio reveals the type, so type prefixing is optional.

3. member variables. prefix with m_
Quote:int m_myinteger

4. global variables. prefix with g_

please post your opinions on this, and i'll update as a consensus is reached.

cheers,
jonathan

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.


[Image: badge.gif]
(This post was last modified: 2010-12-29 15:42 by Gamester17.)
find quote
darkie Offline
Team-XBMC Developer
Posts: 529
Joined: Sep 2003
Reputation: 0
Post: #2
Quote:3. tab indents, with tabstop at four spaces
think two spaces is a bit more readable, and i like it more Smile
Quote:member variables.  prefix with m_
same goes for globals. prefix with g_

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.


[Image: badge.gif]
find quote
Butcher Offline
Retired Developer
Posts: 761
Joined: Dec 2003
Reputation: 0
Post: #3
Quote:variables - use type-prefixed naming style, as it's helpful to know what types we are dealing with from reading
better not to bother:
1. you can easily tell the type of a variable by hovering the cursor over it in vc++ and reading the tooltip.
2. if you decide to change a type you don't have to change every instance of that variable in the code. just imagine if you have int iwidth; and it needs to change to float. you have to change every iwidth to fwidth, not fun.

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.


[Image: badge.gif]
find quote
ezar2003 Offline
Fan
Posts: 338
Joined: Mar 2004
Reputation: 0
Post: #4
Quote:2. if you decide to change a type you don't have to change every instance of that variable in the code. just imagine if you have int iwidth; and it needs to change to float. you have to change every iwidth to fwidth, not fun.
in eclipse you make "refactoring" and it change the code that use this, for example.

read the xbmc online-manual, faq and search the forums before posting! do not e-mail the xbmc-team asking for support!
read/follow the forum rules! note! team-xbmc never have and never will host or distribute ms-xdk binaries/executables!
find quote
chadoe Offline
Team-XBMC Developer
Posts: 627
Joined: Nov 2003
Reputation: 0
Location: Home
Post: #5
Quote:2. braces
i prefer placing the opening brace like this:
Quote:if (int i = 0; i < t; i++) {
[...]
}
else {
[...]
}
just a personal preference, more compact and easier to read i think.

Quote:3. tab indents
using 2 spaces tabindent myself but don't mind using more. what's a bigger problem is using mixed "real tab" indent and space indent, that messes up the code really bad when diffing for instance (or just take a look at those cvs-mails Wink). there are endless discussions about which one to use tabs v spaces

Quote:2. variables - use type-prefixed naming style, as it's helpful to know what types we are dealing with from reading.
also endless discussions about this on the net. personally i don't see any need to prefix the variables except maybe m_ for member variables. it just looks plain ugly and makes the code less readable instead of more readable imho. the variable names should be clear enough, if i really want to know the exact type i'll hover over it with the mouse.

as for global variables (global variables? sounds like visual basic coding to me), here's a nice quote from uno coding guidelines Wink

Quote:don't use global variables! if you think you need a global variable, write a singleton class instead. if you absolutely must use a global variable, reconsider. you really can use a singleton class instead. if you still need that global variable, prefix it with a ``g'' and document it really really well. having created a global variable, consider finding somebody else to program for you.

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.
find quote
Butcher Offline
Retired Developer
Posts: 761
Joined: Dec 2003
Reputation: 0
Post: #6
i prefer globals to singletons where they are required - they are more efficient and imo, it's clearer what is actually happening. people might think they're editing something other than a global with a singleton.

foolish rules such as "no globals" do more harm than good to code quality. you should try to avoid using lots of globals, but flat out banning things is silly. next you'll be saying we should ban gotos.

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.


[Image: badge.gif]
find quote
Nickman Offline
Fan
Posts: 468
Joined: Oct 2003
Reputation: 0
Location: Sweden
Post: #7
(butcher @ aug. 19 2004,11:42 Wrote:next you'll be saying we should ban gotos.
heh that made me think of my c++ teatcher who went through the roof if i used one goto in my code... so when i wrote my first game at home i used goto everywhere just because i could :joker:

some gotoConfused are more then ok. :thumbsup:

  • ASRock ION 330 OpenELEC XBMC Frodo.
  • 47" LG HDTV1080p, AC3/DTS Receiver.
  • 96" Epson LCD 1080p projector
  • 2x Raspbery Pi with XBMC
find quote
jmarshall Offline
Team-XBMC Developer
Posts: 25,689
Joined: Oct 2003
Reputation: 169
Post: #8
Quote:foolish rules such as "no globals" do more harm than good to code quality. you should try to avoid using lots of globals, but flat out banning things is silly. next you'll be saying we should ban gotos.

brilliant! :lol:

ok, i'll drop the requirements on naming as i agree that there is no need for it - just a (bad) habit that i have developed over time. agreed that renaming thing is a pain (i had to recently change a bunch of m_dw... to m_i... Sad

as for the tabs vs. spaces thing:

we all (likely) use the same editor, so we can probably setup msdev so that it auto-uses spaces in place of tabs (options->tabs->use spaces). this will be the optimal solution imo. i don't care about the number, as long as it's uniform.

i assume that any other editors in use (in preference over msdevstudio) will have tabs->spaces support.

more comments are welcome.

cheers,
jonathan

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.


[Image: badge.gif]
find quote
Butcher Offline
Retired Developer
Posts: 761
Joined: Dec 2003
Reputation: 0
Post: #9
now lets not go nuts nickman - you should only use goto if a while, for or if would cause significantly less clear code. i've used about 1 goto in the past 2 years of programming. they are definitely not something to be sprinkled into code all over the place.

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.


[Image: badge.gif]
find quote
Butcher Offline
Retired Developer
Posts: 761
Joined: Dec 2003
Reputation: 0
Post: #10
actually, just checked xbmc - there's almost 100 uses of the keyword goto in the source, almost all mine. Wink

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.


[Image: badge.gif]
find quote
chadoe Offline
Team-XBMC Developer
Posts: 627
Joined: Nov 2003
Reputation: 0
Location: Home
Post: #11
goto is still a valid keyword? damn, i thought they banned it 36 years ago Tongue

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.
find quote
Nickman Offline
Fan
Posts: 468
Joined: Oct 2003
Reputation: 0
Location: Sweden
Post: #12
(butcher @ aug. 19 2004,12:48 Wrote:now lets not go nuts nickman - you should only use goto if a while, for or if would cause significantly less clear code. i've used about 1 goto in the past 2 years of programming. they are definitely not something to be sprinkled into code all over the place.
:lol: offcource. i only missused it because i could.
i didn't mean that all should do it...

  • ASRock ION 330 OpenELEC XBMC Frodo.
  • 47" LG HDTV1080p, AC3/DTS Receiver.
  • 96" Epson LCD 1080p projector
  • 2x Raspbery Pi with XBMC
find quote
Nickman Offline
Fan
Posts: 468
Joined: Oct 2003
Reputation: 0
Location: Sweden
Post: #13
(butcher @ aug. 19 2004,12:56 Wrote:actually, just checked xbmc - there's almost 100 uses of the keyword goto in the source, almost all mine. Wink
:thumbsup: :kickass: :thumbsup:

  • ASRock ION 330 OpenELEC XBMC Frodo.
  • 47" LG HDTV1080p, AC3/DTS Receiver.
  • 96" Epson LCD 1080p projector
  • 2x Raspbery Pi with XBMC
find quote
Bobbin007 Offline
Team-XBMC Developer
Posts: 404
Joined: Oct 2003
Reputation: 0
Location: Germany
Post: #14
(jmarshall @ aug. 18 2004,17:44 Wrote:3. indents, at four spaces.  no tabstops.
 in msdev, go to options->tabs->use spaces.
 this makes cvs run smoother + cvs emails readable.
i'm currently using a tab size of 2 and an indent of 2. the code is readable with these settings. afaik, these where the settings when the project began.

greets

bobbin007

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.


[Image: badge.gif]
find quote
jmarshall Offline
Team-XBMC Developer
Posts: 25,689
Joined: Oct 2003
Reputation: 169
Post: #15
thanks bobbin007.

seeing as that is the second vote for 2 space tabs, i've updated accordingly.

agreed that the code is easier to read with these settings.

Always read the XBMC online-manual, FAQ and search the forum before posting.
Do not e-mail XBMC-Team members directly asking for support. Read/follow the forum rules.
For troubleshooting and bug reporting please make sure you read this first.


[Image: badge.gif]
find quote
Post Reply