In the interest of continuing to give structure to how we work here at MaNGOS, I have republished our Standards And Practices, with modifications and updates by me as necessary while preserving the instruction and intent of the original. Some parts were scrapped entirely and rewritten by me to be more informative and current with the progress of time and the MaNGOS sources. This document, in another form, was originally published on the old MaNGOS web site. I don't have a bibliography as to whom the original author or authors were, but I strongly suspect TheLuda's involvement, at least. If any of our current members had a hand in this document or know who did, please feel free to message me with the details so I may give credit where it is due.

We are all here because we have stood on the shoulders of giants.

While it's focus is primarily on server core development with C++, much of what is presented here can be useful for all MaNGOS developers. I now call upon those masters of database and scripting to step forward and offer any recommendations to this document, so it may be as complete as possible. If anyone notices errors or omissions, please message me with any necessary corrections. This is an ever-evolving document, in keeping with changes to how we work and the technology with which we do that work.

Somebody may want to mirror this in our wiki, too... Chapter 1, Page 1 "So You Want To Be A MaNGOS Dev?"

Introduction

While we here at MaNGOS do our utmost to extend a helping hand to those in need, there is never enough precious time to do everything that needs to be done. You can help us with that by making your best effort to help yourself. When you can learn the basics before jumping into things, it allows us more time to answer the really hard questions about MaNGOS development.

What follows is one avenue where you can teach yourself some valuable fundamentals in how to be a MaNGOS Developer. The rest, and everything that follows, is built upon what you will now read.

This is the official document outlining all the basic methodology for existing and prospective developers. It offers recommendations for everything from correctly configuring and using your Git client, to proper coding style for core patches, to submitting and reviewing code.

All developers and patch contributors are strongly encouraged to read and adhere to these guidelines

Of course, you're free to do as you wish, but it would be nice if you could work with us on this, especially if you want to work with us!

The first thing you do should be to configure a name and email. By default, Git chooses a name based on the GECOS data (which is probably right) and a default email based on your login and hostname (which is almost certainly wrong). Best practices dictate using your real name and email here, not any other aliases you may have, but you may wish to use something other than your real name and personal e-mail if privacy or legal reasons warrant it. These fields will be immortalized in the repository history so make sure you get them right and use the identity by which you wish fame and glory to be heaped upon you.

$ git config --global user.name Your Name         
$ git config --global user.email [email]your@email.addr[/email]ess

While you’re configuring, you may want to enable coloring for some commands:

$ git config --global color.diff auto
$ git config --global color.status auto
$ git config --global color.branch auto
$ git config --global color.interactive auto

If you prefer to use an editor other than the default Vi, such as emacs in the example, specify it like this:

$ git config --global core.editor emacs

Finally, to properly handle line feeds between Windows and Linux, Windows users can use the following setting:

$ git config --global core.autocrlf auto
DOES NOT WORK ON CURRENT VERSION OF msysGit. Checking if this is due to a bug or changes to Git's config.

It is NOT recommended to set autocrlf to "true" as this forces converting CRLF into LF, which has been known to cause issues.

Linux users can set Git to automatically fix CRLF that can sometimes sneak in when a Windows user makes a commit by converting them into standard LF when making a commit:

$ git config --global core.autocrlf input

It is highly recommended to use a single coding style for the whole project source code. Exceptions are allowed for independent libraries used in the project, but it is generally advisable all contributors to use the style specified here.

Failure to adhere to these standards can result in your submitted work being rejected until it has been brought into compliance.

Tab Length

All tabs used in code editing consist of four blank spaces. If your editor allows configuration of the <Tab> key, please set it to use four spaces. Otherwise, do not use the <Tab> key! Instead, use the <Space> key and type in four blank spaces manually. Tab lengths other than four blank spaces are unacceptable. The Microsoft Visual Studio C++ code editor has tabs set to four spaces by default.

Line Length (or Width)

Please use 80-column width, or 80 characters, for line length. This includes spaces and punctuation. If your line is longer than that, please split it into two or more lines. If it's sometimes a little longer, by just a few characters, then it may be permitted at the discretion of the Code Reviewer. If you're splitting text inside brackets { }, the continuing text should be indented to the position after the opening bracket.

printf ("This is a example of how we split lines longer than 80 characters\n"
   "into several so that they won't exceed this limit.\n",
   max_sourcecode_width);

If you have long strings, you can split them as shown above, just remember that C/C++ compilers will glue together several strings that come without any special characters between them into a single string.

Brackets

When writing C++ code, brackets are placed symmetrically, with the ending bracket lined up to the opening bracket.

if (something)
{
 some function
 ...;
}
else
{
 some function
 ...;
}

switch (x)
{
 case 1:
   printf ("X is one!\n");
    break;
  case 2:
 {
   printf ("X is two!\n");
   break;
 }
}

Every bracketed block moves its contents by one tab to right. Labels (but not case selectors!) and public:/private:/protected: C++ keywords are placed at the leftmost indented position for the current block, that is, in the same position where enclosing brackets are. Also please don't use brackets around a single statement because it clutters the code; use brackets only when using non-obvious constructs, like:

if (foo)
{
 if (foo)
   some function
   ...;
}
else
 some function
 ...;

Also, please place one space before opening parenthesis. Before, but not after:

( the if( blah ) style is a no-no! )

(the if (blah) style is correct!)

Following these few and simple formatting styles with your work for MaNGOS will ensure it is readable and easily understood by every developer on the project.

To ensure proper generation of annotated code, please use DoxyGen style comments. This is a bit similar to JavaDoc comments and other automatic code documentation generators.

Single-line documentation or comments should be placed following three slashes.

///This is a single line. I only had a brief thing to say regarding some code.

Documentation and comments that require more than one line should be enclosed in a comment block, which consists of a slash and two asterisks to show the start while the end is indicated by one asterisk and a slash /** ... ... */. All lines between the comment block markers begin with a single asterisk *.

Here's an example that shows most useful keywords you can use in a comment block:

/**
* This function does something very useful. If used with care, this function
* has the potential to make your programs really really useful.
*
* \arg \c x
*  The x argument specifies a integer that is transformed into something useful.
* \arg \c y
*  This argument, if not NULL, is a pointer to a free memory area where this
*  function will put something really really useful.
* \return
*  A useful value, or NULL if error.
*
* Here is a example that you can paste into your code so that it saves you a
* lot of typing:
*
* \verbatim
* for (int x = 0; x < 100; x++)
*   printf ("DoSomethingUseful%d = %s\n", i,
*       DoSomethingUseful (i, &ScratchPad));
* \endverbatim
*
* Paragraphs are split from each other by inserting a empty line. Also some HTML
* tags are supported, like <ol> [<li>...] </ol> and <ul> [<li>...] </ul> for
* ordered (numbered) and unordered (dotted) lists respectively.
*/
char *DoSomethingUseful (int x, void *y);

/// This is a one-line comment
void Something ();

In addition, when you comment-out a line or more of code to prevent it from being used in the source when compiled, use two slashes ( // )at the beginning of each line of code. This is useful for having code as a placeholder until the full function has been completed, a bug remains unresolved elsewhere that breaks your code, or you wish to place debug routines that are not used for normal execution. Please remember to also add a note that the code has been disabled and the reasons for this. Use the standard outlined above for documentation and comments when doing so.

void WorldSession::HandleSetSheathedOpcode( WorldPacket & recv_data )

/*
* This should fix the problem with weapons still being seen as sheathed by
* the client. Should make players happy to know they can now use their 
* weapons in combat!
* Once this has been reviewed, I can do some proper documenting.
*/

{
 uint32 sheathed;
 recv_data >> sheathed;

 //Uncomment the following only when debugging the function.
 //DEBUG_LOG( "WORLD: Recvd CMSG_SETSHEATHED Message guidlow:%u value1:%u", GetPlayer()->GetGUIDLow(), sheathed );

 if(sheathed >= MAX_SHEATH_STATE)
 {
   sLog.outError("Unknown sheath state %u ??",sheathed);
   return;
 }

 GetPlayer()->SetSheath(SheathState(sheathed));
}

Git can be a challenge, especially for those who have been brainwashed by other version control methods like CVS or Subversion. Honestly, Git isn't that hard, once you let go of old ideas and embrace the concept that code can exist in an ever-changing state which can then be frozen in a snapshot of time for your review.

I was once like you, a lost soul, but I was brought into the light! Even as I was shown the way, let me guide you to the holy texts and free your minds, brothers!

If you need an introduction to Git, check out these resources. They're all free!:

Try Git lets you learn how Git works by using it in your web browser. No software installation needed!

Git's documentation page is where you can find the Git Pro Book, the Git Manual, and some introductory videos. And that's just for starters! The Git Pro Book, is also free to download in PDF, EPUB, or mobi formats. The Git Manual is also included with the Git client, as man pages, plain text, or HTML, depending on which platform you are running Git. While you're there, don't forget to download the cheat sheets, for quick access to Git's most commonly used commands and workflow at a glance. Too much more to list here. Give the entire site a good long look.

The Git Reference is an online manual, similar to the Git Manual, but it focuses on actually working with and setting up Git.

Kernel.org also has a mirror of the Git Manual

Git Immersion is an online training course that promises to teach you the fundamentals in a "learn by doing" style. If you don't already have Git installed, they provide links to the client version you will need as the first step.

Git Reference has a similar title to the official Git Reference, but it is meant to be a quick reference for learning and remembering the most important and commonly used Git commands. As you work through each section, every page will also link to more in-depth Git documentation and provide you with an immersive experience that lets you go as deep as you want.

Git Magic is an excellent online book that I highly recommend everyone have on their virtual bookshelf. It has a practical, hands-on approach that teaches you how to use Git by the way you should use Git. Also available in PDF, simplified HTML, and as packages for Debian and Ubuntu (Actually a compressed, lightwieght copy of the web site itself for offline browsing. Did I say it was good, or what?).

Ry's Git Tutorial is mapped out by subjects, in order from beginner to advanced. This one has to be among the best there is for this type of tutorial. Each lesson covers using Git in an actual project, by working with example code and patches on your very own Git repository! If the all the other books, docs, and tutorials just seem too confusing, I'm sure Ry's Git Tutorial is the one for you!

Github Help covers just about every possible question, topic, fact, subject, method, and everything else related to using Github. You definitely want to save this web page in your browser!

That should have you working with Git like a seasoned hacker in a very short time! That gives us more opportunity to help with the MaNGOS-specific problems you may encounter.