WIP: style guide

[TeoTwawki]

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. - Martin Golding

We now have styling info in the project repo itself: https://github.com/DarkstarProject/dark ... tyle-guide

This should help make your changes easy to read and help follow some already existing conventions, which might help get your change merged faster assuming the change is retail accurate.

I have a mix of examples from more than one language here, hope that isn't confusing.

-------------------------------------------------------------------------------

Properly indent your code

Use 4 spaces for a single indention, not tabs. While I never cared which was used (just that ya bloody pick one!) the project seems to want it all spaces now.

2 indention levels should result in 8 leading spaces, not 6, not 9...8.

• 4 x 2 = 8, for you indent challenged folks.

Keep the line ending type the file already had! DSP has not chosen a single standard for line ends. Some files use windows format LEs, some use Unix format LEs. If you change the line ends type Github will show your pull request changed thousands more lines than you think you did!
DSP now prefers Unix Line Ends. See this link.
https://help.github.com/articles/dealin ... e-endings/

If you deal with projects other than DarkStar, you will want to do this per-repository rather than global (they have a section for it on that page) otherwise you can deal with it globally and all pull/commit/push will become Unix line ends automatically.

MS WORD/WORDPAD IS NOT A SUITABLE EDITOR TO WRITE CODE WITH
Get yourself something like notepad++ vim or anything designed to actually edit code. There are tons of options that are 100% free.

Try to limit lines of code to a maximum of 100 characters.

• Exceptions will happen, but try. Typically with well formatted code, you won't go over 80 or so characters anyway.
• the line of dashes above happens to be exactly 80 characters long.
• Generally up/down scrolling is preferable to left/right scrolling as long as your code isn't smelly and hard to read

In Lua, you need the parenthesis around each condition and not every object

Yes:

if ((thing1 and thing3 and thing5) or (thing2 and thing4 and thing6)) then
doStuff()
-- does "stuff" flawlessly anytime either the 3 odd numbered things
-- or the 3 even numbered things are all true.
end

No:

if (thing) and (thing1) and (thing3) or (thing5) and (thing4) and (thing6) then
doStuff()
-- this probably isn't going to behave right
-- and will be harder to spot mistakes
end

In Lua, you need the parenthesis ONLY for making things clear when it isn't obvious.

Code: Select all

 var1 + var2 * var3 / var4 .. 

INDENTION! INDENTION! INDENTION!

• Seriously its crazy how bad some people are at such a simple thing.

1 good indent:

Code: Select all

function getThingDoStuff(player, npc)
    local thing1 = npc:getThing(1)
    local thing2 = npc:getThing(2)
    if (thing1 and thing2) then
        doStuff()
    end
end

2 good indents:

Code: Select all

function getThingDoStuff(player, npc)
    local anotherThing1 = npc:getThing(1)
    local anotherThing2 = npc:getThing(2)
    if thing1 and thing2 then
        if anotherThing1 or anotherThing2 then
            doStuff()
        else
            doOtherStuff()
        end
    end
end

Complete lack of indention:

Code: Select all

-- WHYYYYYYYYYY /wrists
function getThingDoStuff(player, npc)
local anotherThing1 = npc:getThing(1)
local anotherThing2 = npc:getThing(2)
if (anotherThing1 or anotherThing2) then
doStuff()
else
doOtherStuff()
end
end
end

Totally Wrong Indention:

Code: Select all

-- TEO WILL END YOU, YOU PUNK!
function getThingDoStuff(player, npc)
local anotherThing1 = npc:getThing(1)
    local anotherThing2 = npc:getThing(2)
  if (thing1 and thing2) then
        if (anotherThing1 or anotherThing2) then
         doStuff()
else
          doOtherStuff()
   end
   end
 end

Bad indention makes it much harder to visually spot errors, and will often lead to entirely new errors as future editors misread your intentions.



Trim all trailing whitespace.

• Do not create excessive blank space without reason.
• Do not confuse trailing whitespace with leading whitespace.

Do not use Hungarian notation.

• Use lowerCamelCase or SNAKE_CASE (underscores).

OK:

Code: Select all

function goodFunctionName(argument1, argument2)
    stuff
end

NOT OK:

Code: Select all

function BADFUNCTIONNAME(argument1, argument2)
    stuff
end

NOT OK:

Code: Select all

function badfunctionname(argument1, argument2)
    stuff
end

OK:

Code: Select all

    // underscores.
    ENUM GOOD_GENERIC_HEX_ENUM
    {
        THING_1 = 0x0001,
        THING_2 = 0x0002,
        THING_3 = 0x0004,
        THING_4 = 0x0008
    }

Also OK:

Code: Select all

    // Note the casing.
    ENUM alsoGoodGenericHexEnum
    {
        Thing           = 0x0001,
        BiggerThing     = 0x0002,
        EvenBiggerThing = 0x0004,
        JustThing       = 0x0008
    }

NOT OK:
(Tabs and spaces have been replaced with underscores and dashes for visibility)

Code: Select all

____ENUM-badgenerichexenum-//-MY-EYES!
____{
________Thing________________=-0x0001____
-----____BiggerThing________-____=____0x0002-
____-____EvenbiggerThing________=-0x0004________
____----JustThing____________=-0x0008----____--____
________//-Don't-do-this.-Tabs-should-not-be-used-for-alignment.
________//-Don't-mix-spaces-between-tabs-or-tabs-between-spaces...
________//-...And-don't-leave-either-trailing!
____}

It is preferred to fully uppercase compile time constants and use underscores to separate words.
Example:

Code: Select all

const int MAX_THING = 999;

Braces go on the next line:

Code: Select all

	function()
	{
		if (condition)
		{
			DoStuff
		}
	}

Not like this:

Code: Select all

	function(){
		DoStuff
	}

Acceptable but not preferred:

Code: Select all

	function()
		DoStuff

This is bad practice but exists all over the DSP core:

Code: Select all

	if (condition)
	{
		DoStuff
	}
	else
		DoOtherStuff

Somewhat of a personal request here:
Please don't bunch up your code or comments tightly, some contributors that could be helping you are vision impaired and are less likely to offer help if they are straining to see your code. Like me. Lua isn't whitespace sensitive, but my eyes are.

• Also if you are aligning conditionals, please don't put extra whitespace inside braces/brackets/parenthesis.

Good, easy to see:

Code: Select all

// C++ Comment
if (conditions)

Bad, this is harder on the eyes:

Code: Select all

//C++ Comment
if(conditions)

This is just weird, the person who taught you to do this needs slapped:

Code: Select all

if(    condition9 )then
elseif(condition10)then

Don't care what your professor/employer says/made you do, that is still stupid and if I could I'd slap them in person.

[kjLotus]

unix line endings

Code: Select all

git config --global core.autocrlf input

[xipies]

Braces go on the next line:

Code: Select all

	function()	{
		if (condition)
		{
			DoStuff
		}	}

Copy pasta?

[TeoTwawki]

Much copy pasta. Edited the guide I use for another project.

[demolish]

now you just need to clean up the entire project

[TeoTwawki]

I also need Whasf to enable strikethrough on this board.

[whasf]

I also need Whasf to enable strikethrough on this board.

Done

[TeoTwawki]

Thank you