diff options
Diffstat (limited to 'doc/artsbuilder/helping.docbook')
| -rw-r--r-- | doc/artsbuilder/helping.docbook | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/doc/artsbuilder/helping.docbook b/doc/artsbuilder/helping.docbook new file mode 100644 index 00000000..72b2ff2b --- /dev/null +++ b/doc/artsbuilder/helping.docbook @@ -0,0 +1,246 @@ +<!-- <?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>_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_impl</classname>, such as +<classname>SoundServer_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<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> |