Sorry your browser is not supported!

You are using an outdated browser that does not support modern web technologies, in order to use this site please update to a new browser.

Browsers supported include Chrome, FireFox, Safari, Opera, Internet Explorer 10+ or Microsoft Edge.

DarkBASIC Discussion / Program Structure: How To Write Well Presented And Efficient Code

Author
Message
Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 7th Aug 2007 23:55 Edited at: 10th Oct 2008 05:28
How To Write Well Presented And Efficient Code

Quote: "TDK: A main program loop with 200 lines of code and no procedures is untidy, hard to read and shows lack of programming experience."

TDK's Tutorials

It is all well and good being able to write a program that "works"; it is another thing to write a program that can be read, understood and if need be, ammended.
In this tutorial I will provide you with methods to achieve this goal.

Before beginning it is worth bearing in mind that there is no "right" way to structure your code; code structure encompasses everything you do as a programmer and so there are as many methods as commands themselves.

It is also worth mentioning that this is a tutorial exclusively about structure, if you have any questions about how to use commands this is not the place; there are many tutorials that cover commands: such as TDK's http://forum.thegamecreators.com/?m=forum_view&t=99497&b=10

Contents
TOPIC 1: Layout
TOPIC 2: Documentation
TOPIC 3: Planning
TOPIC 4: Economy

Please post your comments in this thread. Any suggestions or corrections will only help to improve this tutorial.
Thanks,

OBese87

A small program that works is better than a large one that doesn't.

DBC Challenge Rank: Rookie
Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 8th Aug 2007 00:14 Edited at: 10th Oct 2008 05:53
TOPIC 1: Layout
Groups
Before we can write structured code, we obviously need a structure.
We can create an organised structure by grouping statements that perform similar tasks.
Grouping subroutines and functions below the main loop keeps them tidy and out of the way.
Always place subroutines before functions; if you declare an array in a subroutine it must come before the function that uses it or the program will crash.

Grouping on a smaller scale further improves the readability of your code.
By grouping similar commands it becomes easier to follow the flow of your code.
e.g.


The Main Loop
The main loop is the hub of a program; it points to all the subroutines and functions that are required to keep the program running.
Try to write it as a conditional loop - when the conditions are met to leave the main loop the program should also end - this enables you to end the program in a much classier way than a do-loop, which forces the user to press F12 before they are allowed to leave.
By definition the main loop should be relatively short consisting mainly of calls rather than actual commands.

Indentation
When a command consumes more than one line, indent the code within the opening and closing statements so that you can clearly see where each command begins and ends. This is of great importance if you ever want help from other coders in the forums :-p.

Here's an example without indentation:


and the same code indented:

There is a vast difference between the two; the latter is much easier to follow.

TOPIC 2: Documentation
Even if your program has a good layout it can still be difficult to see what it does straight away.
Remarks are brief notes you can add to your code to help make it easier to understand, this not only helps others but can also refresh your own memory when you come back to an old program or work in progress.

Here is an example without documentation:

All we can determine from this is that the two-dimensional array "win" has been created, and five values assigned.

and the documented version of the same code:

Now we can clearly see what the array is for, and what each field does.

Headings and Auxiliary Remarks
In the above code, I used two types of remark:
A header remark

and several auxiliary remarks

Auxiliary remarks are very useful as they allow us to document our code and still save lines. However, they can only document a single line of code, so to explain an entire block of code we use a header remark.

Boundaries
You can use symbols in remarks to give your program distinct boundaries. Coming up with your own system of boundaries can help you quickly navigate your code.
Here's an example of the type of boundaries I use.


TOPIC 3: Planning
No-one can write a perfect program in one fell swoop, we'd need some sort of amazing self-programming machine to do that, and the mad programmer who takes on the task will have to plan his code very carefully indeed!
I think of planning in the same way as sketching a portrait; if you start off by drawing the basic shapes, filling in the details later, you'll come away with something quite life-like. If you dive straight in and draw the entire thing without lifting your pencil you're just going to offend people.

Gosub Skeletons
Revisiting our sketch metaphor for a moment: the gosub skeleton is the basic shapes of our portrait; all we are doing is listing the routines that our program will require, we'll fill in the actual code later.

Every gosub should always return to the main loop.

The great benefit of using gosubs in this way is that it makes our program very easy to follow: we can just read the processes our program is going through without having to look through every single line of code and work it out. Another benefit is that while we are in the development phase, we can switch our gosubs on/off (by remming them out) when we want; this is extremely helpful for isolating bugs.

Testing & De-Bugging
Now and then you'll make mistakes, and that's when DB pounces on you and rubs it in your face in the form of a big error message. DB's error messages are famed for not being very informative so you'll have to learn how to fend for yourself in the bug-infested jungles of your code. Learning to root out bugs will save you from hours of tearing your hair out only to find that you've been trying to make DB draw a "corcle".

The most basic method of de-bugging is via process of elimination, as Sherlock Holmes said:
"When you eliminate the impossible, then whatever is left, no matter how improbable, must be the truth."
If we find everything that works, whatever is left must be what doesn't work.
Let's get to it! Since we are good programmers and we have planned out our program into subroutines, this should be easy.

When we rem out the "format_font" gosub our program works fine, it's only when we include it that DB mocks us with its error messages. So that's where our problem is!
Now we could go through the process of remming out each line and narrowing down the problem until we find the exact line that is causing trouble, but since this is a simple syntax error it is quite easy to spot: we have been trying to set the text "funt", I'm not sure what setting the funt does but it's not what we wanted to do. We change "funt" to "font", strip all the rems out of our code and hey-presto, it works! (You cannot set text funt)

All that remming out lines may be quick and painless for smaller programs but with larger ones it is worth writing a small "bug trap" to make DB show you what is going wrong. Most of the time bugs slip past you because the outcome of the offending procedure is not displayed on screen, so... we display it on screen!
This example is based on a DB Challenge entry that I wrote; it is designed to sort the animal names into alphabetical order:

Copy this program into your editor and run it. You'll see that something has gone wrong. The lion seems to have bred another 3 lions and they've eaten the zebra, the tiger and the rhino! To find out what is happening, I've written a "bug trap" that will print the position of each animal in the sort array as the animals are sorted.


Here is the program again with the new bug trap slotted in. Please copy this into your editor and run it.


We can now see that the animal names are not being shifted properly; the higher entries are overwriting the lower ones!
Here's the code with the bug fixed:

Now all the animals are being shifted around properly and are displaying in alphabetical order.

Compatibility
Sooner or later you are going to write a program that you are so proud of you want to share it with the DB community.
How horrible would it be if your moment of shining glory was tarnished by people saying your code didn't work?
The problem is that what works fine on your computer wont necessarily work on other peoples'. Luckily DB lets you standardise the way your programs run. [unfinished]

TOPIC 4: Economy
"It's the economy stupid!" - Ah if only this was a tutorial where each topic had a not-so-witty quote that was very loosely tied to it's subject matter.

Economy serves two masters - the computer and the author - but these masters have a conflict of interests.
When economy reduces the workload of the program by executing every command only when it is absolutely neccessary it serves the computer; when it reduces or modulates the code into independent procedures that are easier to manage and utilise it serves the author.
Economy tends to tip towards the computer when writing very demanding programs but on the whole it is much more beneficial to economise for the author. [unfinished]

Using The Right Commands

Program Speed

A small program that works is better than a large one that doesn't.

DBC Challenge Rank: Rookie
tha_rami
18
Years of Service
User Offline
Joined: 25th Mar 2006
Location: Netherlands
Posted: 8th Aug 2007 06:07
I must argue:

Quote: "Functions can be imported to any program you write, or you could even create your own functions library (a DB program that contains all your functions), then by using the #INCLUDE command you can call any of your functions without them consuming a single line in your program!"


This is untrue, after all, you need to have the #INCLUDE line to be able to call those functions, thus, to be able to call those functions you need a single line.

Besides that, good stuff. Here. You got your compliment. Now finish this. Sheesh... Naah, kidding, good stuff, really. You deserve the compliment.

Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 8th Aug 2007 12:21 Edited at: 8th Aug 2007 14:55
pffft, well it's something that you were being that picky and didn't find anything else wrong
The actual function doesn't take up a line though

[EDIT]
76 views and 1 comment?
I would really appreciate ANY feedback, as this is my first tutorial.

Your signature has been erased by a mod because it was rubbish.
Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 8th Aug 2007 15:12
WTF!!
IT deleted my tutorial!!!
is there a way to get it back?
why are there so many bugs on this forum!!!

Your signature has been erased by a mod because it was rubbish.
Insert Name Here
17
Years of Service
User Offline
Joined: 20th Mar 2007
Location: Worcester, England
Posted: 8th Aug 2007 15:39 Edited at: 8th Aug 2007 15:41
Uh oh...

Sorry Sibraa5.

I never tell the truth.
That ain't a paradox.
I always tell lies is though.
Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 8th Aug 2007 15:42 Edited at: 8th Aug 2007 15:43
Luckily this is pretty recent in my mind so I've been able to re-write most of it in the first thread. I guess that's the way to do it.


I've also saved it in notepad.

Your signature has been erased by a mod because it was rubbish.
Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 8th Aug 2007 15:51
The problem occurred because I accidentally clicked on edit the first post when I wanted to edit the tutorial.
Because I went back it never registered an edited version.
and when I clicked edit the tutorial, it brought up the intro post text. So I thought i'd edit that and it replaced the tutorial!!!

Your signature has been erased by a mod because it was rubbish.
Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 8th Aug 2007 16:31
If a mod is kind enough (and capable) to find my original tutorial post, could you post it here please

Your signature has been erased by a mod because it was rubbish.
Dark Dragon
16
Years of Service
User Offline
Joined: 22nd Jun 2007
Location: In the ring, Kickin\' *donkeybutt*.
Posted: 10th Aug 2007 17:44
.......Thanks. Never knew that much about program structure.....
roddman
16
Years of Service
User Offline
Joined: 24th Jul 2007
Location: Over There
Posted: 10th Aug 2007 19:19
Good job Obese, by the way i'm glad you put something about indenting in there. Makes reading other people's code easier

Cory
Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 12th Sep 2007 13:40 Edited at: 23rd May 2008 21:36
I've updated the tutorial enough to deserve a new post.
It is now at the level I had originally planned, but I want to take it further and talk about planning and economy.
If you have any comments or suggestions please post them here.

It is far better to complete a 10 line program than to start a 10,000 line program.
Not_Maindric
16
Years of Service
User Offline
Joined: 10th Jul 2007
Location: Omaha, NE
Posted: 26th Sep 2007 00:47
So far, it is looking good, I would like to read it when it is completed though...

Phaelax
DBPro Master
20
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 26th Sep 2007 10:18
Just thought I'd point out that modularization isn't always the best. It's definately more user-friendly for the programmers, but can sometimes create redundant code.


Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 26th Sep 2007 19:07
@Phaelax
could you give me an example.
I might put it in

In programming, nothing exists
Kevin Picone
21
Years of Service
User Offline
Joined: 27th Aug 2002
Location: Australia
Posted: 1st Oct 2007 03:49
Well, sometimes you'll only use a few functions from a library, so in those cases everything else is bloat. Including dead code isn't the end of the world, but as your project gets larger it will negatively impact compilation time and program size. Compilation times is more a issue with DB pro than DB Classic however. Although DBc also has a few chestnuts with the size of the source and it's fixed sized string table (constant strings).

Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 1st Oct 2007 04:02
Thanks guys
as you can probably tell from my join date, there are many of you that are more experienced than me so I appreciate the advice

In programming, nothing exists
Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 21st Dec 2007 00:00
I've been working on the planning section of this tutorial so I thought it deserved a BUMP!
It's more of a reference really, maybe I should change the title

Insert Name Here
17
Years of Service
User Offline
Joined: 20th Mar 2007
Location: Worcester, England
Posted: 21st Dec 2007 21:22
Quote: "as you can probably tell from my join date, there are many of you that are more experienced than me so I appreciate the advice
"

The join date is a lie! You became active in 2007!


Sudoku arts, the rabi and Nancy DrewG
jason p sage
16
Years of Service
User Offline
Joined: 10th Jun 2007
Location: Ellington, CT USA
Posted: 21st Dec 2007 22:51
OBese87 - I'm glad you see the importance of formatting. Naming is also very important. Good to see someone thinking of coding style as important.

It's amazing how much easier (though still hard) debugging can be when you apply all these things consistantly.

Eventually code starts to read more like a book than just squashed together syntax.

White Space is your friend - because the compiler ignores it. Nothing wrong with comments.... Separators:

`-------------------------------------
`Comment
`-------------------------------------

etc

Bluestar4
18
Years of Service
User Offline
Joined: 19th Dec 2005
Location: USA
Posted: 23rd Dec 2007 03:14
personally, I dont like using include files unless they are completely independent of the main file and here is why -> If you use a few of them without careful planning it can be disasterous as parts of your code may be inadvertly dependent on functions/routines in your main program that are dependent on varialbes in the main program to make the function work properly so there are scope issues to consider. Secondly , circular reference must also be avoided when using includes.

Libervurto
17
Years of Service
User Offline
Joined: 30th Jun 2006
Location: On Toast
Posted: 23rd Dec 2007 14:07
@Bluestar
I took that part out

Bluestar4
18
Years of Service
User Offline
Joined: 19th Dec 2005
Location: USA
Posted: 24th Dec 2007 01:03
@obese
its something that is definately worth keeping in mind and I'm not sure , but I think that if you use includes that dbc limits the size of your code or files to around 56kb ( I could be wrong on this )

Login to post a reply

Server time is: 2024-03-28 10:01:38
Your offset time is: 2024-03-28 10:01:38