At some point every programmer has experienced it; returning to code written days or months before, you find yourself unable to remember why you wrote the code the way you did and what it was for. Nothing can be more frustrating or more time consuming than having to step back through code and figure out what was going on. There is, however, a way to reduce the risk of this happening again. Adding comments to your source code may seem like a waste of time now, but when you have to go back to a chunk of code months down the road, you will be very thankful you took the time to add a few explanatory comments.
If you have decided to start investing time placing comments in your code, allow me to give you a few “pointers” that will allow your comments to have the greatest impact. The first thing I do is place myself in the position of someone who has never seen that particular code before. I try to imagine I am this person, trying to figure out what the code before me is intended to do. I start out at the beginning of the code with an explanation of what the overall code is trying to accomplish. This will give the reader at least some idea as to what the code is intended to do.
Next, I give a brief description of what each variable’s role is in the code (i.e. counter, output, etc.). The person reading the code could eventually figure out what each variable is doing, but it is easier if you just spell it out for them.
Finally, I add the date. This is an extremely important step. It is extremely likely that sooner or later you will need to make revisions or corrections to your code. By including dates, you and others can see which pieces of code are the newest and which are the oldest. This can be extremely beneficial when debugging programs. I add a date, never erasing previous dates, each time I begin working in a piece of code. I also include a brief description of what was changed and why. This makes for a great reference log for later.
Many programmers find themselves reusing their code in different situations. Adding comments can help locate those needed pieces of code more quickly, saving valuable time. The important thing to remember with comments is that it not only benefits others, but will greatly benefit you in the future. Happy commenting!
About the Author:
Nicholas Brown is a recognized authority on the subject of Access Databases. He is the founder of Database Technology Services (DTS). DTS is a leader in custom Access database development. DTS programmers create databases for corporations, small businesses and individuals. Visit www.dts-consultants.com to see all of the services DTS has to offer.
Grand Prize - Brand New 8GB iPod Touch ($299 value) and One (1) Copy of our New UBD Citrus WordPress Theme (coming next week).
Three (3) runner-up prizes include copies of our new UBD Citrus WordPress Theme.
How do I enter?
Entering the UBD 1-Year Anniversary Contest is super simple!
For one (1) contest entry - just reply to this post with a comment. Only one comment per person will be counted.
For five (5) contest entries - write a blog post about the UBD 1-Year Anniversary Contest and link back to this post. If your blog post does not appear under the “Pingbacks,” leave a comment with a URL to the post.
The winner will be randomly chosen Monday, September 1st, 2008. We will draw the winner via streaming video from the UBD office.
Official Contest Rules
The contest runs from 12:00AM PST Friday, August 22nd, 2008 to 11:59PM Sunday, August 31, 2008.
Winners will be chosen Monday, September 1, 2008 through a random drawing.
Only one (1) comment entry per person and one (1) blog entry per person. The total number of entries any person can receive is six (6) entries.
Prizes include (1) grand prize of an Apple iPod Touch 8GB ($299 value) and three (3) copies of our new UBD Citrus WordPress Theme ($99 value) - coming next week.
March 29, 2008 at 9:47 pm · Filed under Perl, Tutorial
Author: John Dixon
In this article we will discuss how to change the contents of an HTML file by running a Perl script on it.
The file we are going to process is called file1.htm:
Note: To ensure that the code is displayed correctly, in the example code shown in this article, square brackets ‘[..]’ are used in HTML tags instead of angle brackets ”.
[html]
[head][title]Sample HTML File[/title]
[link rel=”stylesheet” type=”text/css” href=”style.css”]
[/head]
[body]
[h1]Introduction[/h1]
[p]Welcome to the world of Perl and regular expressions[/p]
[h2]Programming Languages[/h2]
[table border=”1″ width=”400″]
[tr][th colspan=”2″]Programming Languages[/th][/tr]
[tr][td]Language[/td][td]Typical use[/td][/tr]
[tr][td]JavaScript[/td][td]Client-side scripts[/td][/tr]
[tr][td]Perl[/td][td]Processing HTML files[/td][/tr]
[tr][td]PHP[/td][td]Server-side scripts[/td][/tr]
[/table]
[h1]Summary[/h1]
[p]JavaScript, Perl, and PHP are all interpreted programming languages.[/p]
[/body]
[/html]
Imagine that we need to change both occurrences of [h1]heading[/h1] to [h1 class=”big”]heading[/h1]. Not a big change and something that could be easily done manually or by doing a simple search and replace. But we’re just getting started here.
To do this, we could use the following Perl script (script1.pl):
1 open (IN, “file1.htm”);
2 open (OUT, “>new_file1.htm”);
3 while ($line = [IN]) {
4 $line =~ s/[h1]/[h1 class=”big”]/;
5 (print OUT $line);
6 }
7 close (IN);
8 close (OUT);
Note: You don’t need to enter the line numbers. I’ve included them simply so that I can reference individual lines in the script.
Let’s look at each line of the script.
Line 1
In this line file1.htm is opened so that it can be processed by the script. In order to process the file, Perl uses something called a filehandle, which provides a kind of link between the script and the operating system, containing information about the file that is being processed. I’ve called this “opening” filehandle ‘IN’, but I could have used anything within reason. Filehandles are normally in capitals.
Line 2
This line creates a new file called ‘new_file1.htm’, which is written to by using another filehandle, OUT. The ‘>’ just before the filename indicates that the file will be written to.
Line 3
This line sets up a loop in which each line in file1.htm will be examined individually.
Line 4
This is the regular expression. It searches for one occurrence of [h1] on each line of file1.htm and, if it finds it, changes it to [h1 class=”big”].
Looking at Line 4 in more detail:
$line - This is a variable that contains a line of text. It gets modified if the substitution is successful.
=~ is called the comparison operator.
s is the substitution operator.
[h1] is what needs to be substituted (replaced).
[h1 class=”big”] is what [h1] has to be changed to.
Line 5
This line takes the contents of the $line variable and, via the OUT file handle, writes the line to new_file1.htm.
Line 6
This line closes the ‘while’ loop. The loop is repeated until all the lines in file1.htm have been examined.
Lines 7 and 8
These two lines close the two file handles that have been used in the script. If you missed off these two lines the script would still work, but it’s good programming practice to close file handles, thus freeing up the file handle names so they can be used, for example, by another file.
Running the Script
As the purpose of this article is to explain how to use regular expressions to process HTML files, and not necessarily how to use Perl, I don’t want to spend too long describing how to run Perl scripts. Suffice to say that you can run them in various ways, for example, from within a text editor such as TextPad, by double-clicking the perl script (script1.pl), or by running the script from an MS-DOS window.
(The location of the Perl interpreter will need to be in your PATH statement so that you can run Perl scripts from any location on your computer and not just from within the directory where the interpreter (perl.exe) itself is installed.)
So, to run our script we could open an MS-DOS window and navigate to the location where the script and the HTML file are located. To keep life simple I’ve assumed that these two files are in the same folder (or directory). The command to run the script is:
C:>perl script1.pl
If the script does work (and hopefully it will), a new file (new_file1.htm) is created in the same folder as file1.htm. If you open the file you’ll see the the two lines that contained [h1] tags have been modified so that they now read [h1 class=”big”].
In Part 3 we’ll look at how to handle multiple files.
About the Author:
John is a web developer working for My Health Questions Matter, a company dedicated to helping patients to get the most out of their interaction with health care professionals such as doctors, midwives, and consultants by generating a set of health questions a patient can ask at an appointment.
March 27, 2008 at 9:43 pm · Filed under Perl, Tutorial
Author: John Dixon
Like many web content authors, over the past few years I’ve had many occasions when I’ve needed to clean up a bunch of HTML files that have been generated by a word processor or publishing package. Initially, I used to clean up the files manually, opening each one in turn, and making the same set of updates to each one. This works fine when you only have a few files to fix, but when you have hundreds or even thousands to do, you can very quickly be looking at weeks or even months of work. A few years ago someone put me on to the idea of using Perl and regular expressions to perform this ‘cleaning up’ process.
Why write an article about Perl and regular expressions I hear you say. Well, that’s a good point. After all the web is full of tutorials on Perl and regular expressions. What I found though, was that when I was trying to find out how I could process HTML files, I found it difficult to find tutorials that met my criteria. I’m not saying they don’t exist, I just couldn’t find them. Sure, I could find tutorials that explained everything I needed to know about regular expressions, and I could find plenty of tutorials about how to program in Perl, and even how to use regular expressions within Perl scripts. What I couldn’t find though, was a tutorial that explained how to open one or more HTML or text files, make updates to those files using regular expressions, and then save and close the files.
The Goal
When converting documents into HTML the goal is always to achieve a seamless conversion from the source document (for example, a word processor document) to HTML. The last thing you need is for your content authors to be spending hours, or even days, fixing untidy HTML code after it has been converted.
Many applications offer excellent tools for converting documents to HTML and, in combination with a well designed cascading style sheet (CSS), can often produce perfect results. Sometimes though, there are little bits of HTML code that are a bit messy, normally caused by authors not applying paragraph tags or styles correctly in the source document.
Why Perl?
The reason why Perl is such a good language to use for this task is because it is excellent at processing text files, which let’s face it, is all HTML files are. Perl is also the de facto standard for the use of regular expressions, which you can use to search for, and replace/change, bits of text or code in a file.
What is Perl?
Perl (Practical Extraction and Report Language) is a general purpose programming language, which means it can be used to do anything that any other programming language can do. Having said that, Perl is very good at doing certain things, and not so good at others. Although you could do it, you wouldn’t normally develop a user interface in Perl as it would be much easier to use a language like Visual Basic to do this. What Perl is really good at, is processing text. This makes it a great choice for manipulating HTML files.
What is a Regular Expression?
A regular expression is a string that describes or matches a set of strings, according to certain syntax rules. Regular expressions are not unique to Perl - many languages, including JavaScript and PHP can use them - but Perl handles them better than any other language.
In part 2, we’ll look at our first example Perl script.
About the Author:
John is a web developer working for My Health Questions Matter, a company dedicated to helping patients to get the most out of their interaction with health care professionals such as doctors, midwives, and consultants by generating a set of health questions a patient can ask at an appointment.
March 1, 2008 at 10:50 am · Filed under Game Articles
One of my favourite games when I was a young’n was Street Fighter, yes I am old enough to have played Street Fighter One. But Street Fighter 2 was the game I wasted most of my money on. I found a video of the upcoming Street Fighter 4 game for the next gen systems. Looks nice, but seems like they just slapped on 3-D’ish graphics on to the same games, with a couple more special moves. But we will see, still can’t wait to see it.
February 26, 2008 at 1:50 pm · Filed under Game Articles
Well, I heard about this a couple of weeks ago, but I am just got around to writing about it today, after reading some news about it, I did search through Google to find there homepage. Nothing much up there except a small video (see below). I am really excited about this game, and can’t wait for it to come out. I think Guitar Hero III is a game where the money I spent on it was well deserved. I have never played a game this much, and I am not even close to finishing it, because I am still stuck on Hard level.
But Guitar Rising sounds awesome, you will be able to plug in ANY guitar and not only is it a fun game ala Guitar Hero, but it will actually teach you the proper strings, so you are playing, but also learning. This is a great idea and I can’t believe it has take so long for someone to figure out to do this. You will be able to level at your own pace, starting from the beginning couple of notes moving on to expert.
One thing I hope they improve on before the game comes out is that they only annouce 30 songs that come with game. Hopefully there will be more you can download or buy, because 30 songs is not much. I mean Guitar Hero III comes with 100 or so, and after completing Easy, Medium, and most of Hard, I am getting a little tired of ‘em. Plus I am playing on the Wii so nothing downloadable yet =(
I must say I like the layout of these tutorials better, it not only shows you the code, but there is examples with Screen shots, so the walk thru to install and start running your first game with VB and XNA seems like a simple couple of steps.
I will delve further into these tutorials later, but for now, enjoy this great find.
February 15, 2008 at 9:37 am · Filed under Tutorial, dotNET
Found a bunch of great learning tools for Microsoft .NET using DirectX over at MSDN. This is a great resource, and Code is provided while he explains it, and also as a download, so you can save on the typing. Not sure if you have installed what you need to get started? Not to worry, in every article he provides links to download the Free software you will need to continue the tutorials and learn.
A quote from the site
This series as aimed at beginning programmers who are interested in developing a game for their own use with the .NET Framework and DirectX. The goal of this series is to have fun creating a game and learn game development and DirectX along the way. Game programming and DirectX have their own terms and definitions that can be difficult to understand, but after awhile, you’ll crack the code and be able to explore a new world of possibilities. I will keep things as straightforward as possible and decode terms as they appear. Another part of the learning curve comes from the math you’ll need to deal with DirectX. I am going to point out some resources along the way that will help you brush up on, or learn, the math skills you’ll need to keep going in DirectX.
In this series, we are going to build a simple game to illustrate the various components of a commercial game. We will cover how to create great looking graphics in 3D, how to handle user input, how to add sound to a game, how to create computer opponents using Artificial Intelligence, and how to model real-world physics. In addition we are going to cover how to make your game playable over the network and how to optimize your game for performance. Along the way, I will show you how to apply principles of object-oriented development and, as well, I will share some of my experience in creating well-organized and elegant code.
