The unofficial coding best practise and code formatting conventions for XBMC

goto is still a valid keyword? damn, i thought they banned it 36 years ago

(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...

(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.

:thumbsup: :kickass: :thumbsup:

(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

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.

i currently use "real" tabs in vs.net. am i the only one?

btw, this is how most switch statements in the window classes are currently written:

Quote:switch
{
case gui_msg_1:
{
onmsg1();
}
break;

case gui_msg_2:
{
onmsg2();
[some other code]
}
break;
}

to discuss, if we keep it that way and add it to the conventions.

greets

bobbin007

Maybe slightly off-topic but I like to request that we start requiring basic doxygen tags/comments in XBMC code (including patches). bobbin007 added a few doxygen tags/comments to XBMC CVS a few monts back but it never seem to catched on. BTW, see MPlayer uses it now too

Also, always prefer American English over British English in comments and strings!

maybe borrow this text/guidelines bellow from mplayer (or parts of it?)?, what do you all think?:

Quote:date: tue, 31 aug 2004 09:14:36 +0900
from: attila kinali <attila@kinali.ch>
subject: [mplayer-dev-eng] code documentation guideline draft
to: "mplayer-dev-eng@mplayerhq.hu"

heyo,

i used 5 free minutes to put a code documentation guideline together.
please review it and tell me anything you dont like or that should
be improved.

attila kinali
-------------- next part --------------
code documentation guidelines
=============================

about this guide
----------------

due to the ever increasing complexity and size of mplayer it became quite hard
to maintain the code and add new features. part of this problem is the lack
of proper documentation what the code in question does and how it is doing it.
to tackle this problem every part of mplayer should follow these guidelines
on what and how code should be documented.


doxygen
-------

mplayer uses doxygen for its code documentation. it generates html files
which contain the specially tagged comment lines from the code including
cross references. to generate it type `make doxygen` in the source root
directory. it will generate the files in docs/tech/doxygen. to clear them
again, you can use `make doxygen_clean`.
for further information about doxygen and its sources please have a look
at their website: http://doxygen.sf.net


what should be documented?
--------------------------

- every function, no matter whether it is globally or just locally used
* what the function does
* all parameters and return values of the function and their valid ranges
* all side effects (to passed parameters, globals etc)
* all assumptions made within the function

- global, file local and important variables
* what it is used for
* its valid range
* where it is set (optional)
* where validity checking is done (optional, mandatory for variables which
are set by something external, eg user parameters, file information etc)

- #define, typedefs, structs
* all global definitions
* all local definitions whos use is not imediatly clear by their name
(as a rule of thumb, it's better to document too much then not enough)
* all dependencies

- non-trivial parts of the code
* tricky parts
* important parts
* special side effects
* assumptions of the code
* string operations and why they are safe

- workarounds
* why they are needed
* how they work
* what side effects they have

if you are unsure whether a comment is needed or not, add one.


how should it be documented?
----------------------------

all comments should be in correct and clear english. any other language is
not allowed. the language used should be kept simple as the code will be
read mostly by non-native speakers. for function and variable documentation,
a style usable by doxygen should be used. see section 3 "documenting the code"
of the doxygen manual for an introduction. a very short overview follows:

doxygen includes only special comments in the documentation, those are:

/// this is a line used by doxygen.

/** this one, too */

/** these
here
of
course,
too */

//! this form can be also used

// this line isn't included in doxygen documentation.

/* neither is this. */

there are a couple of special tags for doxygen:

\brief <one line text>
gives a brief description of a function.
\param <parameter> <text>
describes a specific <parameter>.
\return <text>
describes the return value.
\a <word>
mark next word as a reference to a parameter.
\e <word>
use italic font for the next word.
\b <word>
use bold font for the next word.
\c <word>
use typewriter font for the next word.
\sa <references>
adds a section with crossreferences.
\bug <text>
describe a known bug.
\todo <text>
add a todo list.
\attention <text>
add a section for something that needs attention.
\warning <text>
add a section for a warning.
\anchor <refname>
set an invisible anchor which can be used to create a link with /ref.
\ref <refname> [<text>]
add a link to <refname>.

for a complete list of tags please read section 20 "special commands" of the
doxygen manual.

ps! ffmpeg has now also started using doxygen to document their source code.

i don't think we'll ever reach an agreement on this thing.

can you sumbit an updated code style text and also put it in cvs?

thanks,

-yuval

(yuvalt @ sep. 06 2004,17:05 Wrote:i don't think we'll ever reach an agreement on this thing.
-yuval

i agree! there will ever be an agreement about coding standard and formatting.
but... by using a code beautifier, we could increase the quality on this code and make it more readable for every body.

i have been using gc (great code) for a while and it works fine for me. the only switch you desperately need is
"-no-code_decl_move_top-" since the default is to move declarations to the top of the scope and the could ruin the code since also class objects with constructors will be move.
the rest is just cosmetics. my opinion is that gc beautifies to much (read: changes to much), but using a beautifier gives you and your co-programmers so much back that i'm wiling to accept that

if gc is to be used, the gc.cfg file (at least containing "-no-code_decl_move_top-") could be added to cvs root directory.

most of the part of this topics discussion could then be about the gc.cfg file

some words about code beautifier
=========================
q. how to introduce them in a project?
a. check out all code and parse the beautifier through the files, then check in the code without doing any other changes :thumbsup:

q. doesn't a good programmer write code that is more readable than what a beautifier could do?
a. yes, but how many of us does really take us the time of doing that :shifty:

q. could i thrust a beautifier?
a. yes, but first read this how can i trust beautifier programs??!!

also read this from: how to write unmaintainable code :joker:
never beautify: never use an automated source code tidier (beautifier) to keep your code aligned. lobby to have them banned them from your company on the grounds they create false deltas in pvcs (version control tracking) or that every programmer should have his own indenting style held forever sacrosanct for any module he wrote. insist that other programmers observe those idiosyncratic conventions in "his " modules. banning beautifiers is quite easy, even though they save the millions of keystrokes doing manual alignment and days wasted misinterpreting poorly aligned code. just insist that everyone use the same tidied format, not just for storing in the common repository, but also while they are editing. this starts an rwar and the boss, to keep the peace, will ban automated tidying. without automated tidying, you are now free to accidentally misalign the code to give the optical illusion that bodies of loops and ifs are longer or shorter than they really are, or that else clauses match a different if than they really do. e.g.
if(a)
 if(b) x=y;
else x=z;