boberman
2008-08-27 01:46:57
Hello all. My name is boberman and I will be your guide for programming. This will be very general. If I give any code examples, they will either be pseudo-code (Fake code that can't compile) or Scar based. Im not going to teach how to use a specific language per say. More this tutorials goal is to make your programs look better, run smoother and be easier to maintain.
I will hit many subjects and they aren't really going to be linked, so feel free to treat all the text under red big text as their own sections. Ok lets begin.
Design
Believe it or not. Every good program is based on a good design. Many programmers fail to recognize this in favor of the "Hack it out" method. However. generally when they are hacking it out. they are doing the exact same logic they would have done if they developed a design. The problem is that the code starts to look like a big mess when you do this. :duh:
There are several elements to a good design. I will try to hit the basics of how to approach design.
Step 1:
Identify what you want to do with your program. It may sound weird, but a lot of time the most overwhelming part of programming is trying to figure out what the heck you want to do with your program/script. The best thing to do is break it down so you know where you are headed.
Step 2:
Identify what you know how to do and start breaking down the description from step one until you get there.
For example. If I wanted to make a miner and banker the first thing I would say is. OK what do we need to do?
We need to make sure we have a pickaxe.
We need to deposit all our garbage into the bank
we need to run to the mine.
we need to mine the ore.
and we need to come back to the bank and deposit the goods.
Then we need to repeat that process.
Already you skilled scripters might be seeing the next step in each of those statements. we will take the first as an example.
We need to make sure we have a pickaxe.
First how do we tell somethings a pickaxe and not just a rock or Empty space?
How do we do that? Would a bitmap tolerance work? maybe. Maybe some color is unique to the pickaxe (unlikely). How about a DTM? That should work. Or maybe we could do a Dynamic DTM. Yes, that could work to.
Now how would we make sure the player has one?
Lets search his inventory for one, that would work. But what if it is equipped. Then we will need to search his equipment tab as well? What if one is in the bank? We could search their as well.
And what do we do if there isn't one?
We could stop the script? Or maybe we could buy one, they are cheap at the GE. ect..
As you can see, the routes are nearly limitless to what direction you could take. And no one answer is really much better then the other. As your designing your program you will be in charge of weighing in the value of each method.
Step 3:
Repeat step 2 till you are at basic SRL or scar functions :D.
If you do these 3 steps until you work out the order of operations, you're script will be halfway completed before you ever need to turn on your computer! For the most part, this is a procedural approach thats known as a "Top down" design (You can google it if you like) the other is bottom up. That one to me is harder (You make all the functions you think could be useful then you put them together to make the script!)
For the most part, that should be all you ever have to do for design.
Functions
What are functions? Functions are like mini-programs inside your program. They are extremely useful for keeping code clean and neat. When I first started programming I had no such thing, nor any idea when I should or shouldn't have one. I hope I can convey some idea of when to make something a function.
The basic rule of thumb for a function is that it should do one thing. You should be able to thing of it like a sentence (With no conjunctions). for example. I could have a function that deposits ore. There you go. To describe it I would say "This function deposits or" A bad example of a function is one who's description looks like this "This function deposits ore then runs back to the mine". Functions should never fit a complex sentence description. Only simple sentences.
The main goal is to make sure that functions are fairly short. They generally shouldn't be more then a page long. However they may be as short as you like. (I have made useful functions that where only 1 line long).
Functions really help you as a programmer. They make it much easier for you to trackdown bugs and errors. They also make it easier to work as a team. Often, when something is failing you will often already know where they are just because functions help you memorize where things are in your program. functions are your friends. Use them.
Functions are also nice because they allow you to easily re-use code you (or somebody else) has written. This is quite handy, since you don't have to reinvent the wheel. So use them, or die! :P
Constants and globals, the good and the bad
What are Constants? Constants are pieces of data that don't change at all. They are very useful for inputing a number over and over again when you need to. They make your code more readable and maintenance a breeze. It is much easier to change one constants value then having to hunt down every number when something changes in your script.
For example. PI
Now, if you had a script that did a lot of Trig, then PI becomes infinitely useful. Lets say that at first the value of pie, really didn't have to be close. so you used 3. for PI. One day, 3 just doesn't cut it. So you expand it to 3.1425. Now, Imagine if you hadn't used a constant for PI. you would have to go through an entire script (Upto 700 lines of code sometimes) And determine if each number was in fact PI or just a 3 that was needed for something else. I hope you can see how errors could easily creep in.
Now, if you used a constant. then it would be as simple as flicking a switch. Change the value to 3 at the constant and you are down with it.
Globals on the other hand can be very, very, bad. The reason is because rather then you changing the value of global, you are trusting the program to (And someone else might have written the code to do that). Now imagine. you use globals everywhere in your script (Many members applications do this. I don't like it at all). one day, you decide you want to take a function from script a and put it in script b. unbeknownst to you (And trust me, you will forget what you put in functions) you used a global variable bob in script A.
This can end badly in two ways. The first is that the compiler will give you a warning every time you compile because it can't find bob. Thats bad, but manageable. But what if it compiles fine? What if you already created a global named bob for use in another function in the script? Chaos would ensue. all the sudden the value of bob becomes unpredictable and you may eventually scrap the script or rewrite the function because you can't figure out whats going wrong.
Even if they are two functions of the same script, that senerio could still happen. Trust me. Don't use globals.
So what about global constants? These are, OK. but should be minimalized. the general rule for variables and constants is to have them on the lowest level possible (IE make them as close to the place where the will be used as possible) If only one function uses a constant then you shouldn't make that constant global, rather make it a constant for the function.
In summary. Constants good, globals bad.
Comments
Comments are a vital part of programming. That is why every programming language that I can think of supports them. One of the hardest things for programmers to do is write comments as they go (I know, I tend to forget as well) but it is oh so important.
Every function that you write should have a header comment, so to speak. Describing what the function does and what the input variables (if any) control. From there on, comments become more a preference thing. Generally, if you ever write something down that you think "Hey, thats really clever" Or something you had to sit down and think about for a while you should comment it.
This helps other programmers that read your script understand what is going on, as well as help you remember what is going on should something fail as you are scripting (Trust me, you won't always remember why you wrote something or what it does)
Don't get overally ambitious with the comments though. It is fine writing a paragraph for a really complex statement, but don't write anything for statements that any beginner would very easily be able to deduce the meaning of. An example of a bad comment would be
a := 1 // sets a to 1
A good comment would be
c := a * a + b * b; // Pythagorean theorem.
Spacing and Indentation
This is one of the most important aspects of making readable code. Spacing helps the human mind split off things into sub-groups and see better digest the entire picture. code without it is nearly unreadable for most.
I have read several different rules on when to space or how many spaces go into an indent. The basic principle is, BE CONSISTENT. (and consistently good) For example, if you indent with 2 spaces or 4 really doesn't matter. what matters is that you are indenting after if statements, loop statements, ect.
White space can also be very useful for making code readable. I have a hard time giving a good rule of thumb, for me, I just know when to add it :D. I guess the basic rule I follow is that if things are somewhat unrelated, at a white space between them (That is, two returns instead of just one) Yes you increase your code lines, but your code starts to look better and more readable.
Conclusion
Hopefully you found these tips useful. If you apply them, you will easily get in as a member. If I can think of more Ill edit this and add them on.
I will hit many subjects and they aren't really going to be linked, so feel free to treat all the text under red big text as their own sections. Ok lets begin.
Design
Believe it or not. Every good program is based on a good design. Many programmers fail to recognize this in favor of the "Hack it out" method. However. generally when they are hacking it out. they are doing the exact same logic they would have done if they developed a design. The problem is that the code starts to look like a big mess when you do this. :duh:
There are several elements to a good design. I will try to hit the basics of how to approach design.
Step 1:
Identify what you want to do with your program. It may sound weird, but a lot of time the most overwhelming part of programming is trying to figure out what the heck you want to do with your program/script. The best thing to do is break it down so you know where you are headed.
Step 2:
Identify what you know how to do and start breaking down the description from step one until you get there.
For example. If I wanted to make a miner and banker the first thing I would say is. OK what do we need to do?
We need to make sure we have a pickaxe.
We need to deposit all our garbage into the bank
we need to run to the mine.
we need to mine the ore.
and we need to come back to the bank and deposit the goods.
Then we need to repeat that process.
Already you skilled scripters might be seeing the next step in each of those statements. we will take the first as an example.
We need to make sure we have a pickaxe.
First how do we tell somethings a pickaxe and not just a rock or Empty space?
How do we do that? Would a bitmap tolerance work? maybe. Maybe some color is unique to the pickaxe (unlikely). How about a DTM? That should work. Or maybe we could do a Dynamic DTM. Yes, that could work to.
Now how would we make sure the player has one?
Lets search his inventory for one, that would work. But what if it is equipped. Then we will need to search his equipment tab as well? What if one is in the bank? We could search their as well.
And what do we do if there isn't one?
We could stop the script? Or maybe we could buy one, they are cheap at the GE. ect..
As you can see, the routes are nearly limitless to what direction you could take. And no one answer is really much better then the other. As your designing your program you will be in charge of weighing in the value of each method.
Step 3:
Repeat step 2 till you are at basic SRL or scar functions :D.
If you do these 3 steps until you work out the order of operations, you're script will be halfway completed before you ever need to turn on your computer! For the most part, this is a procedural approach thats known as a "Top down" design (You can google it if you like) the other is bottom up. That one to me is harder (You make all the functions you think could be useful then you put them together to make the script!)
For the most part, that should be all you ever have to do for design.
Functions
What are functions? Functions are like mini-programs inside your program. They are extremely useful for keeping code clean and neat. When I first started programming I had no such thing, nor any idea when I should or shouldn't have one. I hope I can convey some idea of when to make something a function.
The basic rule of thumb for a function is that it should do one thing. You should be able to thing of it like a sentence (With no conjunctions). for example. I could have a function that deposits ore. There you go. To describe it I would say "This function deposits or" A bad example of a function is one who's description looks like this "This function deposits ore then runs back to the mine". Functions should never fit a complex sentence description. Only simple sentences.
The main goal is to make sure that functions are fairly short. They generally shouldn't be more then a page long. However they may be as short as you like. (I have made useful functions that where only 1 line long).
Functions really help you as a programmer. They make it much easier for you to trackdown bugs and errors. They also make it easier to work as a team. Often, when something is failing you will often already know where they are just because functions help you memorize where things are in your program. functions are your friends. Use them.
Functions are also nice because they allow you to easily re-use code you (or somebody else) has written. This is quite handy, since you don't have to reinvent the wheel. So use them, or die! :P
Constants and globals, the good and the bad
What are Constants? Constants are pieces of data that don't change at all. They are very useful for inputing a number over and over again when you need to. They make your code more readable and maintenance a breeze. It is much easier to change one constants value then having to hunt down every number when something changes in your script.
For example. PI
Now, if you had a script that did a lot of Trig, then PI becomes infinitely useful. Lets say that at first the value of pie, really didn't have to be close. so you used 3. for PI. One day, 3 just doesn't cut it. So you expand it to 3.1425. Now, Imagine if you hadn't used a constant for PI. you would have to go through an entire script (Upto 700 lines of code sometimes) And determine if each number was in fact PI or just a 3 that was needed for something else. I hope you can see how errors could easily creep in.
Now, if you used a constant. then it would be as simple as flicking a switch. Change the value to 3 at the constant and you are down with it.
Globals on the other hand can be very, very, bad. The reason is because rather then you changing the value of global, you are trusting the program to (And someone else might have written the code to do that). Now imagine. you use globals everywhere in your script (Many members applications do this. I don't like it at all). one day, you decide you want to take a function from script a and put it in script b. unbeknownst to you (And trust me, you will forget what you put in functions) you used a global variable bob in script A.
This can end badly in two ways. The first is that the compiler will give you a warning every time you compile because it can't find bob. Thats bad, but manageable. But what if it compiles fine? What if you already created a global named bob for use in another function in the script? Chaos would ensue. all the sudden the value of bob becomes unpredictable and you may eventually scrap the script or rewrite the function because you can't figure out whats going wrong.
Even if they are two functions of the same script, that senerio could still happen. Trust me. Don't use globals.
So what about global constants? These are, OK. but should be minimalized. the general rule for variables and constants is to have them on the lowest level possible (IE make them as close to the place where the will be used as possible) If only one function uses a constant then you shouldn't make that constant global, rather make it a constant for the function.
In summary. Constants good, globals bad.
Comments
Comments are a vital part of programming. That is why every programming language that I can think of supports them. One of the hardest things for programmers to do is write comments as they go (I know, I tend to forget as well) but it is oh so important.
Every function that you write should have a header comment, so to speak. Describing what the function does and what the input variables (if any) control. From there on, comments become more a preference thing. Generally, if you ever write something down that you think "Hey, thats really clever" Or something you had to sit down and think about for a while you should comment it.
This helps other programmers that read your script understand what is going on, as well as help you remember what is going on should something fail as you are scripting (Trust me, you won't always remember why you wrote something or what it does)
Don't get overally ambitious with the comments though. It is fine writing a paragraph for a really complex statement, but don't write anything for statements that any beginner would very easily be able to deduce the meaning of. An example of a bad comment would be
a := 1 // sets a to 1
A good comment would be
c := a * a + b * b; // Pythagorean theorem.
Spacing and Indentation
This is one of the most important aspects of making readable code. Spacing helps the human mind split off things into sub-groups and see better digest the entire picture. code without it is nearly unreadable for most.
I have read several different rules on when to space or how many spaces go into an indent. The basic principle is, BE CONSISTENT. (and consistently good) For example, if you indent with 2 spaces or 4 really doesn't matter. what matters is that you are indenting after if statements, loop statements, ect.
White space can also be very useful for making code readable. I have a hard time giving a good rule of thumb, for me, I just know when to add it :D. I guess the basic rule I follow is that if things are somewhat unrelated, at a white space between them (That is, two returns instead of just one) Yes you increase your code lines, but your code starts to look better and more readable.
Conclusion
Hopefully you found these tips useful. If you apply them, you will easily get in as a member. If I can think of more Ill edit this and add them on.