WIP: style guide

Post Reply
User avatar
TeoTwawki
Developer
Posts: 516
Joined: Mon Jul 15, 2013 9:50 pm
Contact:

WIP: style guide

Post by TeoTwawki » Wed Jul 22, 2015 2:16 pm

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

Please note that not following this guide does not mean your changes will be rejected! I am only trying to help. But it 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:

Code: Select all

    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:

Code: Select all

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


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

	if (condition) then

Code: Select all

	-- Lua Comment

Code: Select all

	// C++ Comment
Bad, this is harder on the eyes:

Code: Select all

	if(condition)then

Code: Select all

	--Lua Comment

Code: Select all

	//C++ Comment
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.
Last edited by TeoTwawki on Sun Jul 10, 2016 1:51 am, edited 7 times in total.
Hi, I run The Demiurge server.

Code: Select all

PLS USE [code]CODE TAGS[/code] WHEN POSTING CODE
Image
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. - Martin Golding
DO NOT PRIVATE MESSAGE ME ABOUT BUGS

User avatar
kjLotus
Lead Developer
Posts: 1813
Joined: Sun Jul 22, 2012 2:16 pm

Re: Unoffcial style help.

Post by kjLotus » Wed Jul 22, 2015 7:14 pm

unix line endings

Code: Select all

git config --global core.autocrlf input

xipies
Posts: 119
Joined: Thu Aug 02, 2012 11:29 pm

Re: Unoffcial style help.

Post by xipies » Wed Jul 22, 2015 9:48 pm

teotwawki wrote: Braces go on the next line:

Code: Select all

	function()	{
		if (condition)
		{
			DoStuff
		}	}
Copy pasta?

User avatar
TeoTwawki
Developer
Posts: 516
Joined: Mon Jul 15, 2013 9:50 pm
Contact:

Re: Unoffcial style help.

Post by TeoTwawki » Thu Jul 23, 2015 4:45 pm

Much copy pasta. Edited the guide I use for another project.
Hi, I run The Demiurge server.

Code: Select all

PLS USE [code]CODE TAGS[/code] WHEN POSTING CODE
Image
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. - Martin Golding
DO NOT PRIVATE MESSAGE ME ABOUT BUGS

User avatar
demolish
Developer
Posts: 262
Joined: Thu Jul 26, 2012 7:12 am

Re: Unoffcial style help.

Post by demolish » Thu Jul 23, 2015 5:28 pm

now you just need to clean up the entire project
<Giblet[NewBrain]> kj with this first step would be fine on my shit
Click here for a guide on scripting missions.

User avatar
TeoTwawki
Developer
Posts: 516
Joined: Mon Jul 15, 2013 9:50 pm
Contact:

Re: Unoffcial style help.

Post by TeoTwawki » Thu Jul 23, 2015 5:45 pm

I also need Whasf to enable strikethrough on this board. :(
Hi, I run The Demiurge server.

Code: Select all

PLS USE [code]CODE TAGS[/code] WHEN POSTING CODE
Image
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. - Martin Golding
DO NOT PRIVATE MESSAGE ME ABOUT BUGS

User avatar
whasf
Site Admin
Posts: 1257
Joined: Thu Jul 19, 2012 9:11 pm

Re: Unoffcial style help.

Post by whasf » Thu Jul 23, 2015 6:07 pm

teotwawki wrote:I also need Whasf to enable strikethrough on this board. :(
Done
-- Whasf

User avatar
TeoTwawki
Developer
Posts: 516
Joined: Mon Jul 15, 2013 9:50 pm
Contact:

Re: Unoffcial style help.

Post by TeoTwawki » Tue Aug 30, 2016 10:10 pm

Thank you :)
Hi, I run The Demiurge server.

Code: Select all

PLS USE [code]CODE TAGS[/code] WHEN POSTING CODE
Image
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. - Martin Golding
DO NOT PRIVATE MESSAGE ME ABOUT BUGS

Post Reply