Difference between revisions of "Coding Guidelines"

From Mumble Wiki
Jump to: navigation, search
(Naming: - add section for #define guard naming)
(add commenting section)
Line 60: Line 60:
  
 
''Tipp: (If you need to add some local ignores specific to you or your environment, which you do not want to add and/or commit, add them to your <code>.git/info/exclude</code> file)''
 
''Tipp: (If you need to add some local ignores specific to you or your environment, which you do not want to add and/or commit, add them to your <code>.git/info/exclude</code> file)''
 +
 +
 +
= Coding =
 +
== Commenting ==
 +
Comments are to be put *above* the code they comment.
 +
 +
// Easy way to check if m_userList was changed by the model
 +
bool m_dirty;
 +
 +
Avoid trivial comments. Comment’s should point out reasoning of implementation rather than the implementation itself. Only if the code is not obvious by itself make it clear with a comment.
  
  
 
[[Category:Development]]
 
[[Category:Development]]

Revision as of 13:53, 15 September 2013

Intro

Here you can find some guidelines you can orient to when writing code for Mumble. Be aware that when browsing existing Mumble code it is likely you will be able to find code not adhering to the rules written down here. In such cases feel free to submit a patch.

Please note that this page is a work in progress and as such incomplete or possibly even partly wrong. If we bring something up during review not listed here please add it.

Filetype/Encoding

  • Newlines: Unix style (\n, a.k.a. LF)
  • Encoding: UTF-8 without BOM
  • Indentation: Tab

Naming

Naming classes

Class names should be CamelCase and descriptive of the object. Example:

class OpenURLEvent : public QEvent

Naming member variables

Class member variables use loose Systems Hungarian prefixing and are mixedCase. Example:

   QString qsDesiredChannel;
   bool bSuppressAskOnQuit;


Naming member functions

Class member function names should be mixedCase. An exception to this rule can be Qt slots (see below). Example:

   void msgBox(QString msg);
   void setOnTop(bool top);


Naming slots

Slots generally are named just like member functions. If you like you can prefix them with an "on" to indicate that they are slots. However Mumble uses the Qt signal&slot auto-connection feature extensively, so when handling signals from members functions will be named on_member_signal (prefix "on", underscore, member name, underscore, signal name). Example:

   void onRecorderError(int err, QString strerr);
   void on_qpbStart_clicked();


Naming function parameters

Function parameter names are mixedCase and, in contrast to member variables, are not prefixed.

bool setVolumeForSessionControl2(IAudioSessionControl2 *control2, const DWORD mumblePID, QSet<QUuid> &seen);


Naming locals

Local names are mixedCase and, in contrast to member variables, are not prefixed.

   QString formatString;


Naming #define guards

#define guards are named in the form

<PROJECT>_<PATH>_<FILE>_H_

to make them unique to the file.

Structure

Git Ignores

One .gitignore file in the main repositories folder. All ignores go in there, with path-restrictions where useful/possible. (For easier maintainability. Just one place to check for.)

Tipp: (If you need to add some local ignores specific to you or your environment, which you do not want to add and/or commit, add them to your .git/info/exclude file)


Coding

Commenting

Comments are to be put *above* the code they comment.

// Easy way to check if m_userList was changed by the model
bool m_dirty;

Avoid trivial comments. Comment’s should point out reasoning of implementation rather than the implementation itself. Only if the code is not obvious by itself make it clear with a comment.