Jump to content

[Beginner] Naming Conventions - Keeping It Clean!


Dealman

Recommended Posts

In this tutorial I'll go ahead and teach you how to keep your code clean, when to lower-case and upper-case letters to keep your code similar to "the standard".

Usually you'll see people write most of their code entirely in lower-case, for those of you whom are looking to later get more involved with scripting and foremost programming - such as studying, should know how to properly name your functions and variables.

Pascal Case and camelCase

Pascal Case

While not necessary, this is considered the standard way of naming your identifiers whether you're scripting in Lua, C++ or C#. In C# you'll always want to name your namespaces, classes and methods using Pascal Case. In Lua, this means you'll want to name functions using Pascal Case.

What Pascal Case means is that you capitalize the first letter of each word, an example would be;

function ThisIsWrittenInPascalCase() 
    -- Code here 
end 

camelCase

On the other hand, whenever you name a variable or for example a parameter(basically anything that isn't the equivalent of a namespace, class or a method), you'll write it in camelCase. Meaning that the first word will be written with a lower-case letter - and the rest of the words will start with a capital letter.

An example of this would look like this;

local thisIsWrittenInCamelCase = "I'm a variable!" 

Of course I want to stress that this really isn't necessary, it'll work either way. But if you think you'll want to study programming - you'll most likely be going for C++ or C#, and as such - already knowing small details like these will strike some bonus points with your teacher.

Also, if whatever you made is released to public - other programmers will appreciate code that is structured well and written nicely.

Naming Your Functions

Often you'll see people around these forums to structure their script like this;

addEvent("exampleEvent", true) 
addEventHandler("exampleEvent", root, 
    function() 
        -- Code here 
    end 
) 

And while this is fine, writing it like this means you can't name your function - leading to issues should you need to call the function through another one. Personally I think it's always better to write it like you would in for example C#, where you give your functions an identifier(a name) which describes what that function does.

For example if I were to write a function that prints "Hello World!" - I'd write it like this;

function PrintHelloWorld() 
    print("Hello World!") 
end 

If I were to write the above event-handler in a similar way - it would look like this;

function ExampleEvent_Handler() 
    -- Code here 
end 
addEvent("exampleEvent", true) 
addEventHandler("exampleEvent", root, ExampleEvent_Handler) 

Writing it like this would allow me to call this function elsewhere, for example if I need call this whenever a player logs in - I could just do this;

function PlayerLogin_Handler() 
    ExampleEvent_Handler() 
end 
addEventHandler("onPlayerLogin", root, PlayerLogin_Handler) 

It's generally considered to be much cleaner writing it in a way like this, rather than writing all of your event-handlers at the bottom of the script - like this;

function PrintHelloWorld() 
    print("Hello World!") 
end 
  
function ExampleEvent_Handler() 
    -- Code here 
end 
  
function PlayerLogin_Handler() 
    ExampleEvent_Handler() 
end 
  
addEvent("exampleEvent", true) 
addEventHandler("exampleEvent", root, ExampleEvent_Handler) 
addEventHandler("onPlayerLogin", root, PlayerLogin_Handler) 

Because when written the other way around, you'll be able to get a general idea of what the function does and when it is triggered much easier - rather than having to scroll back and forth.

Naming Your Identifiers

Language

First and foremost I want to stress that if you are to release a script publicly, with the intention of other people using it and/or modifying - then please, write it in English.

I wholeheartedly understand that some people aren't as good at English as others, since some countries put a much higher effort in teaching English than others do. And some people just have a hard time learning other languages.

But see it like this, if you start trying to write it in English, it's only good for you. Use a translator if you have to, you're not writing a novel, grammar won't matter as much as it would if you were to write a book. If you were to write it in English, it's so much more likely that other people around the globe will be able to understand your code.

It's generally easier to translate FROM English rather than TO English.

Naming Conventions

Always try to name the functions and variables in a logical manner, this will not only help others understand your code - but neither will you get lost in your own code because the functions aren't properly named.

For example it's very common that you'll see player name their functions similar to the event-name, and this might cause some confusion;

function onPlayerLogin() 
    -- Code here 
end 
addEventHandler("onPlayerLogin", root, onPlayerLogin) 

Instead, if you want to write it like this, it's good practice to add _Handler at the "end" of the identifier, making it less confusing to read.

function OnPlayerLogin_Handler() 
    -- Code here 
end 
addEventHandler("onPlayerLogin", root, OnPlayerLogin_Handler) 

However you decide to name the functions is entirely up to you, but it's generally a good idea to keep it as short but also as descriptive as possible. For example if you wanted to greet the player upon logging in - these examples do the same thing and both names describe what they do, but the first one is much shorter and "friendlier to read".

function GreetPlayerOnLogin() 
    outputChatBox("Welcome to our Server!", source) 
end 
addEventHandler("onPlayerLogin", root, GreetPlayerOnLogin) 
  
function WelcomeThePlayerWhenHeLogsIntoHisAccount() 
    outputChatBox("Welcome to our Server!", source) 
end 
addEventHandler("onPlayerLogin", root, WelcomeThePlayerWhenHeLogsIntoHisAccount) 

Indentation(also known as Tabulation)

Indentation is the practice of indenting each "block of code". This makes the code a lot easier to read as it won't be a giant wall of text. For example you can compare these 2, which are exactly the same - but the latter is written much cleaner thus making it easier to read - and to understand.

local exampleid = 1 
function examplecode() 
if exampleid == 1 then 
outputChatBox("It's 1") 
elseif exampleid == 2 then 
outputChatBox("It's 2") 
else 
outputChatBox("It's neither 1 or 2") 
end 
end 
  
local exampleID = 1 
  
function ExampleCode() 
    if(exampleID == 1) then 
        outputChatBox("It's 1") 
    elseif(exampleID == 2) then 
        outputChatBox("It's 2") 
    else 
        outputChatBox("It's neither 1 or 2") 
    end 
end 

Summary

Again, this is not obligatory. You're free to write in whichever way you prefer, but this is generally considered the standard of how code is written. Simply because it's a very nice and clean way of writing your code.

And that's it I guess, I might have forgotten to mention some things - if I did, I'll just edit it later. Obviously, this is a very basic tutorial and isn't really meant to teach you any advanced stuff, just to help give you an idea of how you can write code that is easier not only for you to read - but also others.

If you have any questions I'd be happy to help!

Edited by Guest
Link to comment
    addEvent("exampleEvent", true) 
    addEventHandler("exampleEvent", root, ExampleEvent_Handler) 
    addEventHandler("onPlayerLogin", root, PlayerLogin_Handler) 
      
    function PrintHelloWorld() 
        print("Hello World!") 
    end 
      
    function ExampleEvent_Handler() 
        -- Code here 
    end 
      
    function PlayerLogin_Handler() 
        ExampleEvent_Handler() 
    end 

Wouldn't this give you an error at addEventHandler (expected function at argument 3, got nil)?

Link to comment
  • 3 weeks later...
  • 2 weeks later...
  • 1 month later...
Personally, I prefer using camel case for my custom functions in Lua, simply because it follows the same pattern MTA is using. But it's all personal preference in the end.

Clear and concise guide. I like it!

Aye, and it's a good reason as well. I've simply stuck with pascal case since I've been working with C# :)

Link to comment
  • 8 months later...
    addEvent("exampleEvent", true) 
    addEventHandler("exampleEvent", root, ExampleEvent_Handler) 
    addEventHandler("onPlayerLogin", root, PlayerLogin_Handler) 
      
    function PrintHelloWorld() 
        print("Hello World!") 
    end 
      
    function ExampleEvent_Handler() 
        -- Code here 
    end 
      
    function PlayerLogin_Handler() 
        ExampleEvent_Handler() 
    end 

Wouldn't this give you an error at addEventHandler (expected function at argument 3, got nil)?

Yeah, because the function handler is defined after the event handler, and the server is reading the code from the top to the buttom.

Link to comment
  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...