# Syntax, Lines, Scope

## Comments

Okay before I forget, let's go for one of the most important things. How to comment:

// Single line comment

/*
Multi
Line
Comment
*/

That's the basics
However, in Modern SS13 Code, you should do this

/**
 * This is a datum used to greet people.
 */
/datum/testdatum
    /// The text displayed on greeting
    var/greeting = "Hello"
    /// The person who we belong to
    var/mob/owner

/**
 * Greets the user
 * 
 * @param
 * * override - override for the message used
 */
/datum/testdatum/proc/greet(override)
    // Tell the user our greeting
    to_chat(owner, "<span class='notice'>[override || greeting], [owner]!")

Why?
**The modern DreamMaker language server uses this format to generate descriptions of procs, datums, variables, and more.**
It makes other coder's lives far easier.
**Comments are required to be in the above style - even if you decide not to do the fancy @param stuff, at the very least use the comment block format (automated in visual studio code!) and describe your procs.** We do not want to have to pick apart how your code works later.

**Now, time for the actual programming syntax.**

## Scope

Scope is the concept of what **belongs** to a certain, say, definition, function, control statement block, etc

var/global/gvar = "Test"

/proc/a_proc()
    var/internal_var = "test2"
    if(internal_var == "test2")
        var/nested_var = "test3"
    else
        var/other_var = "test4"

In the above code, `gvar` isn't under any indents - it is a variable on the global scope.
Likewise, `a_proc()` isn't under any indents and has no /typepath before it. It is a global proc.

However, `internal_var` can only be accessed from within the proc - that's the **scope** it's defined to. `nested_var` can only be accessed from **within the if statement** - it's under that 'block' of code, which is its scope. IF you tried to access it from the else statement's block, you would get a compiler error for unknown var - the var doesn't exist in an outside scope.

- tl;dr: Things declared are always usable/visible from inside scopes
- If you declare two things of the same name that can't be distinguished by using `src.` it'll throw a compiler error due to the conflict
- Things inside a certain scope can access things "above" it, but not "below" it - or below any of its above nodes.

## Datum/Object procs, vars

var/a

/proc/gproc()

/datum/testdatum
    var/b
    var/c
    
/datum/testdatum/proc/datumproc()

In this example, `a` and `gproc` can be accesed from **anywhere in the code** - they are global in scope.

`b` and `c` can only be accessed by **referencing** an instance of testdatum, and calling `datumproc` on it. They are declared as part of /datum/testdatum.

### Relative Pathing?

/datum
    testdatum
        var/b
        var/c
        
        proc/datumproc()

You can also do this - or at least, the compiler would let you.
This is called relative pathing. **This is banned in our codebase**, as it makes searching for procs far more obnoxious to do and generally results in less readable code.

## Indents

BYOND determines scope by idents using space and tab.
We use tabs.
Do not ever indent with space - BYOND just counts whitespace characters, so technically mixed indents with space/tab are possible but this is banned, use tabs so it's actually readable

Example:

/datum
    var/correct
 var/wrong

/datum/proc/testproc()
    if(1 == 1)
        thing()
    else
  thing()

An example of horrific indents. The first if statement and the else are properly indented, the thing under the else isn't, even though it'd work fine because it has two spaces, putting it in the same block as the first `thing()`.

## Braces, semicolons
Forced scopes can be done on the same line using {}'s and statements broken up with ;'s

#define thing(T)    if(T){thing();}else{thing2();};

You rarely should be doing this. The only time you should be doing this, is..

## The `\` linebreak

When you put a \ at the end of the line, it breaks into the next line. The compiler however treats this as the same line, allowing for multi-line macros that compile into one line.

var/astring = "This is a multi-line \
    string."

- I'll be entirely honest, the above "break the string in two" is the **only** reason anyone with a beginner's understanding should ever be doing this for.
- If you get to the point of doing performance optimizations and refactors you can look at BINARY_INSERT() for an example on multi line defines but for now don't use {}'s and don't worry about it.