path: root/doc/artsbuilder/helping.docbook

<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd">
To validate or process this file as a standalone document, uncomment
this prolog. Be sure to comment it out again when you are done -->

<chapter id="contributing">
<title>Contributing to &arts;</title>

<sect1 id="how-to-help">
<title>How You Can Help</title>

<para>
The &arts; project can use help from developers to make existing
multimedia applications &arts;-aware, write new multimedia applications,
and enhance the capabilities of &arts;. However, you don't have to be a
developer to contribute. We can also use help from testers to submit bug
reports, translators to translate the application text and documentation
into other languages, artists to design bitmaps (especially for
<application>artsbuilder</application> modules), musicians to create
sample &arts; modules, and writers to write or proofread documentation.
</para>
</sect1>

<sect1 id="mailing-lists">
<title>Mailing Lists</title>

<para>
Most development discussions on &arts; take place on two mailing
lists. This is the place to discuss new feature and implementation ideas
or ask for help with problems.
</para>

<para>
The &kde; Multimedia mailing list is for general &kde; multimedia issues
including &arts; as well as the multimedia applications like &noatun;
and &aktion;.  You can subscribe from the web page at
<ulink url="http://www.kde.org/mailinglists.html">
http://www.kde.org/mailinglists.html</ulink> or send an email with the
subject set to <userinput>subscribe
<replaceable>your-email-address</replaceable></userinput> to
<email>kde-multimedia-request@kde.org</email>. The list is also archived
at <ulink url="http://lists.kde.org"> http://lists.kde.org</ulink>.
</para>

<para>
The &arts; mailing list is for issues specific to &arts;, including
non-&kde; use of &arts;. To subscribe, send an email containing the
message body <userinput>subscribe
<replaceable>your-email-address</replaceable></userinput> to
<email>arts-request@space.twc.de</email>.  The list is archived at
<ulink url="http://space.twc.de/~stefan/arts-archive">
http://space.twc.de/~stefan/arts-archive</ulink>.
</para>

</sect1>

<sect1 id="coding-standards">
<title>Coding Standards</title>

<para>
For getting a consistent reading through all the sources, it is
important to keep the coding style the same, all over the &arts;
source. Please, even if you just write a module, try to write/format
your source accordingly, as it will make it easier for different people
to maintain the source tree, and easier to copy pieces of from one
source to another.
</para>

<variablelist>
<varlistentry>
<term>Naming of member functions</term>
<listitem>
<para>
&Qt;/&Java; style.  That means capitalization on word breaks, and first
letter always without capitalization; no underscores.
</para>
<para>This means for instance:</para>

<programlisting>   createStructureDesc()
   updateWidget();
   start(); </programlisting>

</listitem>
</varlistentry>

<varlistentry>
<term>Class members</term>
<listitem>
<para>
Class members are not capitalized, such as menubar or button.
</para>

<para>
When there are accessing functions, the standard should be the &MCOP;
way, that is, when having an long member <function>foo</function>, which
shouldn't be visible directly, you create:
</para>

<programlisting>   foo(long new_value);
   long foo(); </programlisting>

<para>
functions to get and set the value. In that case, the real value of
<function>foo</function> should be stored in
<returnvalue>&lowbar;foo</returnvalue>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Class names</term>
<listitem>
<para>
All classes should be wordwise capitalized, that means
<classname>ModuleView</classname>,
<classname>SynthModule</classname>. All classes that belong to the
libraries should use the &arts; namespace, like
<classname>Arts::Soundserver</classname>.
</para>
<para>
The implementations of &MCOP; classes should get called
<classname>Class&lowbar;impl</classname>, such as
<classname>SoundServer&lowbar;impl</classname>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Parameters</term>
<listitem>
<para>
Parameters are always uncapitalized.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Local variables</term>
<listitem>
<para>
Local variables are always uncapitalized, and may have names like
<varname>i</varname>, <varname>p</varname>, <varname>x</varname>, &etc;
where appropriate.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Tab width (Shift width)</term>
<listitem>
<para>
One tab is as long as 4 spaces.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Spaces in expressions</term>
<listitem>
<para>
You normally don't need to use spaces in expressions. You can however use
them between operator and their operands. However, if you put a space before
an operator (i.e. +), you also need to put a space after the operator. The only
exception to this are list-like expressions (with ,), where you should only put
a space after the ",", but not before. It's okay to omit the space here, too.
</para>
<para>
The following examples demonstrate good use of spaces:
</para>
<programlisting>
{
    int a,b;
    int c, d, e;
    int f = 4;

    a=b=c=d+e+f;
    a = b = c = d + e + f;

    if(a == 4) {
        a = b = c = (d+e)/2;
    }

    while(b&lt;3)
        c--;

    arts_debug("%d\n", c);
}
</programlisting>
<para>
The following examples demonstrate how <emphasis>not</emphasis> to use spaces.
For function calls, after if, while, for, switch and so on, no space is being
written.
</para>
<programlisting>
{
    // BAD: if you write a list, write spaces only after the ","
    int a , b , c , d , e , f;

    // BAD: non-symmetric use of spaces for = operator
    a= 5;

    // BAD: if is considered a function, and isn't followed by a space
    if (a == 5) {   
    }

    // BAD: don't write a space after while
    while (a--)
        b++; 

    // BAD: functions names are not followed by a space
    arts_debug ("%d\n", c);

    // BAD: neither are member names
    Arts::Object o = Arts::Object::null ();
}
</programlisting>
</listitem>
</varlistentry>


<varlistentry>
<term>Naming of source files</term>
<listitem>
<para>
Source files should have no capitalization in the name. They should have
the name of the class when they implement a single class. Their
extension is <literal role="extension">.cc</literal> if they refer to
&Qt;/&GUI; independent code, and <literal
role="extension">.cpp</literal> if they refer to &Qt;/&GUI; dependant
code. Implementation files for interfaces should be called
<filename><replaceable>foo</replaceable>_impl</filename>, if Foo was the
name of the interface.
</para>

<para>
&IDL; files should be called in a descriptive way for the collection of
interfaces they contain, also all lower case. Especially it is not good
to call an &IDL; file like the class itself, as the .mcopclass trader
and type info entries will collide, then.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>

</chapter>