Tweet
For anyone who may feel the need to post a thread like this allow me to offer some preemptive advice. Starting out in any programming language can be a bit overwhelming and sometimes the next step can be quite elusive.
I know when I first starting coding, conventions were unknown to me and, after developing them over the years, I can see their importance. Without conventions for naming variables, commenting and structuring code, proper organization of your code is nearly impossible. So, I thought I'd offer this little post in an effort to eliminate some of the beginning confusion that can occur with AMS coding. Keep in mind that we're all n00bs in some way or another and for those of you just starting out in AMS...I hope this helps.
All the experienced coders feel free to chime in. I'll add more stuff when I think of it.
Lesson #1: Variables Names
Below I provide a list of variable type indicators. This is my way of doing it, take this example and use what you like and come up with your own stuff too and please, share it so other people can learn from your genius ideas.
Now, keep in mind, that you should be able to look at your code a year from now and decipher it fairly easy. Your variable names should be chosen to reflect their use. Also, they should be concise; long and cumbersome variable names can create clutter and be confusing. If you need to specify several words, try abbreviating meaningfully or using a logical delimiter between the words. Capital letters are very good logic delimiters between words.
Strings
sMyString = a lower case "s" before my variable name indicates that this a non-specific string
pFilePath = this is also a string but the "p" indicates that this is a path to a file or folder.
Boolean
bIsVisible = this is a boolean (true or false).
Numbers
nMyVeryLongNumberVariableName = the "n" tells me this is a number. "i" is also commonly used and stands for "integer". These are, for all intents and purposes, interchangeable in AMS.
Note:In programming languages where variables are declared, these two indicators should not be used interchangeably as they stand for different number types (such as double or float).
Tables
tLetters = "t" stands for table...and the cow says "mooo".
Functions
MyFunction() = I don't typically use a letter in front of function names since a function is always followed by parentheses "()" that may or may not contain arguments.
Userdata and Threads.
These are not typically used by the beginner programmer so we'll come back to these later when we explain them in more detail.
Window and File Handles
hWnd = Although these are numbers, I use "h" to show that they are handles to files or windows. A few, well-chosen, variable type sub classes can make life a whole lot easier.
Locals vs Globals.
A common mistake for newcomers is to, simply, start typing variable names and assigning values without any regard for variable scope. According to the lua documentation, local tables are processed about 30% faster than global tables. That's huge! If a variable does not need to be global, make it local. Now, by default in AMS, all variables are global unless declared otherwise. Use the word local before your variable names to make them local.
Tip! Repeat loops can be a little tricky when using local variables so experiment and figure out what works. Read the AMS documentation for more info on variable scope.
_sProgramName = To indicate a global variable, I use an underscore "_".
local nTotal = Declaring a local variable is as easy as typing the word "local" before it.
Lesson #2: Object Naming
Haphazardly naming objects can be confusing and result in the complete and utter destruction of the universe...or some catastrophe closely related. In each object's name field I place a prefix (three letters and always the same for a given object type) and the name of the object. Also, I use all lower case for my objects. This makes enumerating object types easy and also makes a quick glance at your code valuable and informative.
Prefixes Examples
CheckBox = "chk save file"
Paragraph = "par details"
Input = "inp password"
I think you get the idea. Whatever three letters upon which you decide, stick to them! Changing prefixes mid-program will defeat the purpose of this method (unless you change them all). I would recommend deciding upon your prefixes (within a reasonable amount of time) and never changing them so you'll be able to look back on previous code and get the gist of its structure and function quickly.
Lesson #3: Commenting, White-space and Indenting and Posting Code
Comments
Now, everyone has a different opinion of this part of coding. I'll give you mine and you can get others' from them. When writing plugins, I rarely comment my code. The code in my plugins is structured and the functions named in such a manner that all of it is, basically, self-explanatory.
When writing programs, I comment frequently and concisely. My comments are not lengthy but they are descriptive. Also, I comment only in places where comments are needed.
For example,
For me, the above code would not require a comment as it's pretty clear what's going on here. As the code becomes more complex, the comments should become more frequent.
White-space and Indenting
Consider this code,
Having one's code all smashed together, especially when you've got a thousand lines of it, makes logic section distinction quite difficult. Leave a little space.
Take at look at this,
Even with some white-space, distinguishing the logic statement bounds is very difficult since I have not indented my code. The first time you write five embedded logic statements, try writing them with and without indentation and you'll see the difference.
Posting Code
There are many examples on this forum of people posting their code like this,
local tLetters = {"a","b","c","d","e","f","g","h","i","j"};
if tLetters then
for nIndex, sLetter in pairs(tLetters) do
if sLetter == "a" then
Dialog.Message(nIndex, "This is the letter "..sLetter);
end
end
end
I usually pass right by these posts (unless I stop to say, "Please post your code using the CODE or PHP tags"). I have no intention of spending my time sorting out someone's mess. Many others here feel the same way as is clear from their posts regarding this issue. Most folks around here have no problem helping newcomers (or old timers for that matter) as long as it's clear that some effort went into their process and there is no mess to clean up before hand. So, do yourself a favor when asking for help with code and post it using indentation, white-space and a CODE or PHP tag.
Like this...
Lesson #4: RTFM!
This should probably be lesson one....
RTFM stands for Read the [email protected]*&^%$ Manual. Yes, read read read. When a newcomer asks a question like, "How do I get the text from an input object?" the response is generally unanimous, "RTFM!". Like, I said, we are all here to help each other and don't mind giving help except when it is quite clear that someone just wants us to do the work for them. IR has done an amazing job with the help file, it is a valuable resource for learning AMS and where I spent the first year and a half of my n00bhood.
I know when I first starting coding, conventions were unknown to me and, after developing them over the years, I can see their importance. Without conventions for naming variables, commenting and structuring code, proper organization of your code is nearly impossible. So, I thought I'd offer this little post in an effort to eliminate some of the beginning confusion that can occur with AMS coding. Keep in mind that we're all n00bs in some way or another and for those of you just starting out in AMS...I hope this helps.
All the experienced coders feel free to chime in. I'll add more stuff when I think of it.
Lesson #1: Variables Names
Below I provide a list of variable type indicators. This is my way of doing it, take this example and use what you like and come up with your own stuff too and please, share it so other people can learn from your genius ideas.
Now, keep in mind, that you should be able to look at your code a year from now and decipher it fairly easy. Your variable names should be chosen to reflect their use. Also, they should be concise; long and cumbersome variable names can create clutter and be confusing. If you need to specify several words, try abbreviating meaningfully or using a logical delimiter between the words. Capital letters are very good logic delimiters between words.
Strings
sMyString = a lower case "s" before my variable name indicates that this a non-specific string
pFilePath = this is also a string but the "p" indicates that this is a path to a file or folder.
Boolean
bIsVisible = this is a boolean (true or false).
Numbers
nMyVeryLongNumberVariableName = the "n" tells me this is a number. "i" is also commonly used and stands for "integer". These are, for all intents and purposes, interchangeable in AMS.
Note:In programming languages where variables are declared, these two indicators should not be used interchangeably as they stand for different number types (such as double or float).
Tables
tLetters = "t" stands for table...and the cow says "mooo".
Functions
MyFunction() = I don't typically use a letter in front of function names since a function is always followed by parentheses "()" that may or may not contain arguments.
Userdata and Threads.
These are not typically used by the beginner programmer so we'll come back to these later when we explain them in more detail.
Window and File Handles
hWnd = Although these are numbers, I use "h" to show that they are handles to files or windows. A few, well-chosen, variable type sub classes can make life a whole lot easier.
Locals vs Globals.
A common mistake for newcomers is to, simply, start typing variable names and assigning values without any regard for variable scope. According to the lua documentation, local tables are processed about 30% faster than global tables. That's huge! If a variable does not need to be global, make it local. Now, by default in AMS, all variables are global unless declared otherwise. Use the word local before your variable names to make them local.
Tip! Repeat loops can be a little tricky when using local variables so experiment and figure out what works. Read the AMS documentation for more info on variable scope.
_sProgramName = To indicate a global variable, I use an underscore "_".
local nTotal = Declaring a local variable is as easy as typing the word "local" before it.
Lesson #2: Object Naming
Haphazardly naming objects can be confusing and result in the complete and utter destruction of the universe...or some catastrophe closely related. In each object's name field I place a prefix (three letters and always the same for a given object type) and the name of the object. Also, I use all lower case for my objects. This makes enumerating object types easy and also makes a quick glance at your code valuable and informative.
Prefixes Examples
CheckBox = "chk save file"
Paragraph = "par details"
Input = "inp password"
I think you get the idea. Whatever three letters upon which you decide, stick to them! Changing prefixes mid-program will defeat the purpose of this method (unless you change them all). I would recommend deciding upon your prefixes (within a reasonable amount of time) and never changing them so you'll be able to look back on previous code and get the gist of its structure and function quickly.
Lesson #3: Commenting, White-space and Indenting and Posting Code
Comments
Now, everyone has a different opinion of this part of coding. I'll give you mine and you can get others' from them. When writing plugins, I rarely comment my code. The code in my plugins is structured and the functions named in such a manner that all of it is, basically, self-explanatory.
When writing programs, I comment frequently and concisely. My comments are not lengthy but they are descriptive. Also, I comment only in places where comments are needed.
For example,
PHP Code:
local tLetters = {"a","b","c","d","e","f","g","h","i","j"};
if tLetters then
for nIndex, sLetter in pairs(tLetters) do
Dialog.Message(nIndex, "This is a the letter"..sLetter);
end
end
White-space and Indenting
Consider this code,
PHP Code:
local tLetters = {"a","b","c","d","e","f","g","h","i","j"};
if tLetters then
for nIndex, sLetter in pairs(tLetters) do
Dialog.Message(nIndex, "This is the letter "..sLetter);
end
end
Take at look at this,
PHP Code:
local tLetters = {"a","b","c","d","e","f","g","h","i","j"};
if tLetters then
for nIndex, sLetter in pairs(tLetters) do
if sLetter == "a" then
Dialog.Message(nIndex, "This is the letter "..sLetter);
end
end
end
Posting Code
There are many examples on this forum of people posting their code like this,
local tLetters = {"a","b","c","d","e","f","g","h","i","j"};
if tLetters then
for nIndex, sLetter in pairs(tLetters) do
if sLetter == "a" then
Dialog.Message(nIndex, "This is the letter "..sLetter);
end
end
end
I usually pass right by these posts (unless I stop to say, "Please post your code using the CODE or PHP tags"). I have no intention of spending my time sorting out someone's mess. Many others here feel the same way as is clear from their posts regarding this issue. Most folks around here have no problem helping newcomers (or old timers for that matter) as long as it's clear that some effort went into their process and there is no mess to clean up before hand. So, do yourself a favor when asking for help with code and post it using indentation, white-space and a CODE or PHP tag.
Like this...
PHP Code:
local tLetters = {"a","b","c","d","e","f","g","h","i","j"};
if tLetters then
for nIndex, sLetter in pairs(tLetters) do
if sLetter == "a" then
Dialog.Message(nIndex, "This is the letter "..sLetter);
end
end
end
Lesson #4: RTFM!
This should probably be lesson one....
RTFM stands for Read the [email protected]*&^%$ Manual. Yes, read read read. When a newcomer asks a question like, "How do I get the text from an input object?" the response is generally unanimous, "RTFM!". Like, I said, we are all here to help each other and don't mind giving help except when it is quite clear that someone just wants us to do the work for them. IR has done an amazing job with the help file, it is a valuable resource for learning AMS and where I spent the first year and a half of my n00bhood.
Comment