Difference between revisions of "Coding Style"

From AMule Project FAQ
Jump to: navigation, search
Line 96: Line 96:
  
 
* Use ALLUPPERCASE names
 
* Use ALLUPPERCASE names
 +
 +
* 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.
  
 
===== Filenames =====
 
===== Filenames =====
Line 104: Line 106:
  
 
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.
 
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 =====
 
===== References =====
  
 
Always use references where passing large datatypes suchs as [http://www.wxwidgets.org/manuals/2.4.2/wx368.htm ''wxString''] and ''CMD4Hash'' and only use non-const references if we are going to change the passed variables.
 
Always use references where passing large datatypes suchs as [http://www.wxwidgets.org/manuals/2.4.2/wx368.htm ''wxString''] and ''CMD4Hash'' and only use non-const references if we are going to change the passed variables.
 +
 +
 +
=== Lists/etc ===
 +
 +
Only use raw arrays when absolutely nessesary, in ALL other cases use:
 +
1) STL containers, or
 +
2) CList/CTypedPtrList, or
 +
3) wxWidgets containers
 +
 +
However, for consistency STL containers should always be used unless there is a major reasons for doing otherwise. Using STL containers also gives us the advantage of making possible to use the many algorithms in the STL library and STL containers are usually faster than the corresponding wxWidgets container.
 +
 +
=== Deleting ===
 +
 +
It is not needed to check pointers before deleting them, so checks against NULL only clutter the code needlesly. Such checks should only be used in cases where there is an need, as for instance in the Packet destructor.
  
 
=== Hacks ===
 
=== Hacks ===
Line 123: Line 135:
 
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.
 
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!) ===
+
== 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.
 
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.
Line 145: Line 157:
  
 
''As a side note, debug messages should be ALWAYS in english, and messages meant to be for the user should be translated. This is so we can read debug info without translating it.''
 
''As a side note, debug messages should be ALWAYS in english, and messages meant to be for the user should be translated. This is so we can read debug info without translating it.''
 
  
 
Probably more things I should remember, so I'll make this list bigger later.
 
Probably more things I should remember, so I'll make this list bigger later.

Revision as of 21:15, 6 February 2005

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

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.


Lists/etc

Only use raw arrays when absolutely nessesary, in ALL other cases use:

1) STL containers, or
2) CList/CTypedPtrList, or
3) wxWidgets containers

However, for consistency STL containers should always be used unless there is a major reasons for doing otherwise. Using STL containers also gives us the advantage of making possible to use the many algorithms in the STL library and STL containers are usually faster than the corresponding wxWidgets container.

Deleting

It is not needed to check pointers before deleting them, so checks against NULL only clutter the code needlesly. Such checks should only be used in cases where there is an need, as for instance in the Packet destructor.

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.

When you use a string to build a wxString, like "aMule", you MUST use wxT("aMule") if you want it not to be translated and _("aMule") if you want it to be translated. Failure to do so will result in aMule not being compilable in unicode mode, and the coder responsive will be killed and buried alive, not neccesarily in that order.

As a side note, debug messages should be ALWAYS in english, and messages meant to be for the user should be translated. This is so we can read debug info without translating it.

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