Coding Style

This article details the coding style that should be adopted when writing changes to the aMule codebase.

Formatting

Indenting

Use tabs

Always use tabs for indenting, do not use spaces. The size of each tab should be equal to 4 spaces.

Scopes

Indent inside new scopes, including classes, structs, functions, etc.

Examples:

 if ( false ) {
   ...
 } else {
   ...
 }

 class foo
 {
   foo() {
     ...
   }
 }

Whitespace

Place whitespace between brackets and keywords, and between operators and variables:

 if (something == true);

rather than

 if(something==true);

Brackets

Brackets are placed on the same line as the construct with the exception of non-inlined functions, structs and classes. Perfer the usage of brackets, even when optional, as in the case of if/while/etc blocks.

Misc

When using the trinary operator, place brackets to promote readability.
Add a space after the // chars when writing comments.

Documenting comments

Always remember to documment new functions and classes! Examples of documented classes can be found in can be found in CMD4Hash.h, BarShader.*, ServerListCtrl.* and others. More information on the usage and syntax of doxygen can be found in the doxygen documentation.

Use the following format, which is doxygen compatible.

Functions, classes, structs, etc

  /**
   * <Short description>
   *
   * [@param <Param_1 description>]
   * [@param <Param_n description>]
   * [@return <return value description>]
   *
   * [Long description]
   * [@see <reference to other relevant function>]
   */

Variables, typedefs, constants, etc

  //! <Description>

Coding

Naming Style

Always try to use descriptive names, except when it adds nothing to the readability, such as iterator varibles and counters (it, i, x, y, etc).

Functions

Function names should follow the AllWordsAreUppercase convention
Function arguments should follow the conventions for local varibles described below

Variables

Names should follow the firstWordLowerCaseRestUpperCase convention
Prefix global variables with g_
Prefix static variables with s_
Prefix member variables with m_

Classes

Prefix classnames with C
Names should follow the AllWordsAreUppercase convention

Constants

Use ALLUPPERCASE names

Filenames

For classes, use the classname without the "C" prefix.

Const correctness

Remember to mark functions and arguments (pointers, references) as const where possible. This increases the ability for us to write safer code and is a good thing.

Consts vs. Defines

Whenever possible, prefer const variables to pre-compiler defines. We've already had problems with nameclashing caused by defines, so me might as well not increase the chances of it happening again. Actual constants also has the major advantage that we gain proper type-safety.

References

Always use references where passing large datatypes suchs as wxString and CMD4Hash and only use non-const references if we are going to change the passed variables.

Hacks

Always try to avoid odd hacks and in general try to avoid abnormal stuff, assignments in if constructs and the like for instance should be avoided when possible. Also try to avoid the usage of void pointers as they result in a almost total loss of type-safety.

Helper-functions

Helper functions which can have use across the app should be placed in otherfunctions.h.

Whenever possible, prefer wxWidgets functions to system calls, as this reduces the dependencies on specific function-calls that may or may not be available on other platforms.

IMPORTANT: What to avoid (The special 'I kill you' section!)

Do NEVER NEVER use unicode2char and char2unicode functions at all. Same for unicode2UTF8 and UTF82unicode, and anything related to converting unicode wxStrings into char or wchar buffers. This is specially true with functions dealing with interface, where we should ALWAYS use wxStrings, and never use string conversion to construct that wxString.

The only places this is allowed is on printf() calls for debug. And if you REALLY need to use them in other scenario, like network communication or file handling use them VERY carefully. There are comments about the proper use at the beggining of StringFunctions.h. If you don't know if it's right or what to use, just ask, probably Kry is the best one to reply to that questions. Make someone review the code if you're not experienced and want to use that.

Do NEVER use wxFile or wxFFile - use CFile instead. It has several bugfixes over wxFile, and it will work perfectly for handling UTF8 filenames on unicode aMule, such as anything non-ascii.

There should be no problem using wxFile and wxFFile for amule-related files, like server.met and others, that are never unicoded, but the use of CFile is advisable to keep coherence over the system and easier replacement when a valid wxFile is released from wxWidgets devs.

Do NEVER use wxFind{First,Next}File. Use the CDirIterator class found in CFile.*. Reasons for this are the same as for wxFile and wxFFile: they don't handle unicode filenames properly.

No, there's not exception for this. Just never use it.

Avoid wxDateTime::Now().Format{Time, Date} as if it was Satan itself. Mainly, it asserts and breaks on several locale, mainly chinese and other asian languages. Use wxDateTime::Now().FormatISO{Time, Date}. People will have to live with english formated date and time strings.

No excuses for this either. It will have to go like this till wx fixes it.

Probably more things I should remember, so I'll make this list bigger later.