WARNING - This blog post is long

Some Background Info

I had the need to do this for work recently. It was nothing short of a right royal pain in the butt. It was such a pain, in fact, that I have decided to document what I had to do to get it working so that other poor unfortunates will feel less pain if they have to do this themselves.

Almost regardless of the company and the software I'm working on, I use Mercurial for source code control. For the work I am doing at the moment, I was also using hg because the company I am involved with is relatively new and they hadn't yet sorted out a plan for version control or ALM. It was working quite well and I was pushing all my changes to my NAS box to make sure I had other copies backed up, etc. I was living the dream

The problem, though, was that this setup was working fine for me as a sole developer, but wasn't solving the problem for the other developers. There are two other people involved in development, and until now most of the work they have been doing has been in a different area to the bits I have been doing. Sharing and merging code was done by email patches. Those developers weren't using version control as far as I'm aware.

So given the volume of changes and the number of merges that were happening, it was well past time to get something proper in place that we could all use. The original plan was to go with an installation of TFS to handle all of these issues for us. Personally, I am not a huge fan of TFS. The experience I've had with it so far hasn't been great. It also has a shocking effect on the speed of my IDE (I seem to have no choice but to use integration with the IDE, which again isn't great).

To cut this part of the story short, we had issues getting TFS to work. We tried installing a few times, tweaking here and there, but we never managed to get it to work. I know I could have called a TFS guru, such as Snagy to pick his brains and perhaps ask him nicely to help out, but he's a busy man and there's no guarantee that we wouldn't have to start again from scratch. I wasn't really up for that, and neither was my boss.

So I told him that I thought it might just be easier to get a server running with Mercurial for the version control, and Trac for issue tracking and project "stuff". Not only would it mean that I could just push my local repository to the server and have the entire history transferred (TFS would have been latest version only) but it would save us a substantial cost in license fees, remove the need for VS integration, and everyone could be up and running with a DVCS in no time.

My boss, being the legend he is, gave me the thumbs up! Awesome.

So the rest of this post is dedicated to what was involved in getting things set up. If you're not interested, then go read something else

The need for a bit of security

Needless to say, the IP that we're building is something that my employer is rather protective of! And rightly so. Hence it won't come as a surprise to hear that security of this information is very important. I decided that having Mercurial run over plan old HTTP would be a bad idea. I was keen to have it tunnel via SSH, and have all clients authenticate using their own private keys. Hence, getting an SSH server was going to be part of the setup.

Web server

IIS is already installed on the server, and running another web server seemed like overkill. I didn't want to expose tracd directly over the web as it doesn't support SSL, so I wanted to get it running under IIS instead. This added another little bit of complexity to the install.

What to download

There were quite a few bits that I needed to download to get this working, they're listed below. At first it might not be obvious as to why these things are needed, just trust me

First, server-side components:

1. Python 2.5.4 - Get this version, not anything earlier or later if you want this guide to work! (download)
2. Setuptools (download)
3. ClearSilver (download)
4. PySqlite (download)
5. flup (download)
6. Trac installer v0.11.4 (download)
7. Mercurial (download)
8. Subversion (download)
9. Apache Tomcat AJP Isapi filter (download)
10. Junction (download)
11. CopSSH (download)
12. Windows Server 2003 Resource Kit (download)

Next, client-side:

1. Mercurial (download)
2. PuTTy (download)

Quite a lot isn't it

Server: Setting up the Python Environment

1. Execute the Python installer. This by default installs Python to C:\python25.
2. Modify the environment variables so that the Python install folder is included in the PATH.
3. Execute the Setuptools installer.
4. Execute the PySqlite installer.
5. Install the downloaded python eggs:
1. Open a command prompt
2. Navigate to the folder where your .egg files are downloaded to.
3. in the command line, type: easy_install [filename.egg].
4. Do this for ClearSilver and flup.

At this point, you should have a working installation of Python 2.5.4 with the required eggs and plug-ins.

Server: Setting up Mercurial

1. Execute the Mercurial installer. By default this installs to %programfiles%\Mercurial. Feel free to change this if you like.
2. During the installation, the installer will ask if you want to include the install folder in the system PATH. Make sure you click "yes", otherwise you'll have to do it manually afterwards.

The Mercurial client is now installed. Later on when installing Trac and getting it to work with Mercurial, I had issues because the Mercurial doesn't install the Mercurial bindings for Python. No only that, trying to use easy_install to install it didn't work because I didn't have Visual Studio 2003 installed on the server (nor did I want to install it!). It turns out that you can get round the issue by doing this:

1. Go to the Mercurial installation folder using Windows Explorer.
2. Locate the file Library.zip.
3. Open this file with an application like WinRAR or 7-zip (using the built-in Windows zip functionality doesn't work!).
4. Inside that archive there is a folder called mercurial. Extract this folder to a disk.
5. Open another Windows Explorer and navigate to your Python installation directory (eg. C:\Python25). Open up the Lib sub0folder (that's lib, not libs).
6. Copy or move the extracted mercurial folder to the lib folder.

Done! You've just "installed" the Mercurial bindings for Python. Later down the track, Trac will not crap out when you try and use it!

Server: Setting up TracMercurial

Given that we're using Mercurial for the back-end version control, we're going to need to set up and install the Mercurial plugin for Trac. This is where the need for SVN comes in. Yes, it's ironic that you need SVN to get something working with Mercurial! Just do it, ok!?

1. Execute the Subversion installer and let it go through with the default installation.
2. Make sure that the path to the SVN binaries is included in the system PATH environment variable.
3. Open up a command prompt and change directory to a temporary location.
4. run the command: svn co http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin-0.11 - this gets the right version of the plug-in from source.
5. run the command: cd mercurial-plugin-0.11
6. run the command: python setup.py bdist_egg - this creates an installable python egg.
7. run the command: python setup.py install - this installs the plug-in to the global location.

The TracMercurial plug-in is now installed. We'll need to configure it slightly when we've installed Trac. That information is listed in the next section.

Next we need to create a repository which will be used to house our source code. We'll pretend we're creating a project called "Slartibartfast".

1. Create a new folder on the file system somewhere meaningful, such as C:\Repos.
2. Open a command window, and change directory to that folder.
3. create a folder for your project: mkdir Slartibartfast.
4. Change to that folder: cd Slartibartfast.
5. Initialise the repository: hg init . (not the '.' at the end).

Your repository is now ready for code!

Server: Setting up Trac

We'll start with the basic install:

1. Execute the Trac installer.
2. Default installation settings are fine.
3. It will be installed to the scripts folder under the Python installation folder.

At this point it's a good idea to also add the scripts folder to the system PATH. This gives us the ability to run Python scripts from anywhere.

Next up, let's create a Trac project for our Slartitbartfast project.

1. Create a folder to house your Trac projects, say C:\Trac
2. Open a command window and change directory to your Trac projects folder.
3. Create a folder for your new project: mkdir Slartibartfast
4. Change to that folder: cd Slartibartfast.
5. Start the Trac administration application to start an interactive setup session: trac-admin . initenv

You need to fill out some values as it asks for them. Here's a sample interactive session that I did as a test run:

C:\Trac\Slartibartfast>trac-admin . initenv
Creating a new Trac environment at C:\Trac\Slartibartfast

Trac will first ask a few questions about your environment
in order to initialize and prepare the project database.

 Please enter the name of your project.
 This name will be used in page titles and descriptions.

Project Name [My Project]> Slartibartfast

 Please specify the connection string for the database to use.
 By default, a local SQLite database is created in the environment
 directory. It is also possible to use an already existing
 PostgreSQL database (check the Trac documentation for the exact
 connection string syntax).

Database connection string [sqlite:db/trac.db]>

 Please specify the type of version control system,
 By default, it will be svn.

 If you don't want to use Trac with version control integration,
 choose the default here and don't specify a repository directory.
 in the next question.

Repository type [svn]> hg

 Please specify the absolute path to the version control
 repository, or leave it blank to use Trac without a repository.
 You can also set the repository location later.

Path to repository [/path/to/repos]> C:\Repos\Slartibartfast

Creating and Initializing Project
 Installing default wiki pages

**
** craploads of import statements go here **
**

---------------------------------------------------------------------
Warning: couldn't index the repository.

This can happen for a variety of reasons: wrong repository type,
no appropriate third party library for this repository type,
no actual repository at the specified repository path...

You can nevertheless start using your Trac environment, but
you'll need to check again your trac.ini file and the [trac]
repository_type and repository_path settings in order to enable
the Trac repository browser.

---------------------------------------------------------------------
Project environment for 'Slartibartfast' created.

You may now configure the environment by editing the file:

  C:\TracProjects\Slartibartfast\conf\trac.ini

If you'd like to take this new project environment for a test drive,
try running the Trac standalone web server `tracd`:

  tracd --port 8000 C:\TracProjects\Slartibartfast

Then point your browser to http://localhost:8000/Slartibartfast.
There you can also browse the documentation for your installed
version of Trac, including information on further setup (such as
deploying Trac to a real web server).

The latest documentation can also always be found on the project
website:

http://trac.edgewall.org/

Congratulations!

You may notice the message: Warning: couldn't index the repository.
Don't be too concerned at this point, as we need to do a bit more to make sure that the Mercurial stuff is working.

Now we should test to make sure we're able to start the Trac daemon and see if the project site has been set up. We do that by executing the statement they suggested in the output:
tracd --port 8000 C:\TracProjects\Slartibartfast
Then we browse to http://localhost:8000 to see if it works! If all goes well you should see a project listing. Click on Slartibartfast and you should see something like this:

Trac is telling us why it's not able to index the repository, it's because we haven't enabled the plug-in yet. Let's do that now.

Open up the Trac.ini file which is located inside the conf folder under the main project folder (eg C:\Trac\Slartibartfast\conf\Trac.ini).

First, add the following section to the ini file:

[hg]
# -- Show revision number in addition to the changeset hash
show_rev = yes

# -- Changeset hash format
node_format = short
# hex:   Show the full SHA1 hash
# short: Show a shortened hash for the changesets

Then enable the Mercurial plugin by adding the following:

[components]
tracext.hg.backend.csetpropertyrenderer = enabled
tracext.hg.backend.hgdefaultpropertyrenderer = enabled
tracext.hg.backend.hgextpropertyrenderer = enabled
tracext.hg.backend.mercurialconnector = enabled

Note:Make sure that the [hg] and [components] sections don't already exist. If they do, then add the respective lines to the existing sections rather than creating new ones. For a fresh install, these sections shouldn't already exist, so you should be safe to add them.

Kill the tracd instance by press CTRL+C, then restart it (press the up arrow, then enter). Refresh your browser window and this time you should see this:

Excellent, our project is up and our repository is able to be read. We're done!

Server: Setting up the Trac Daemon as a Service

The tracd needs to run as a service. This is to make sure it's always running in a way that IIS can reference it. Given that we're later going to be hooking this up to IIS, we need to make sure it uses the AJP protocol. Here are the required steps:

1. Install the Windows 2003 resource kit.
2. Open a command window, and navigate to where the resource kit binaries are installed. On my system that was at C:\Program Files\Windows Resource Kits\Tools
3. Create a service called "Trac" by executing the following command: InstSrv Trac "C:\Program Files\Windows Resource Kits\Tools\SrvAny.exe" - (note the use of the full path is necessary for this to work).
4. Next we need to hack the registry a little to pass the right parameters and have the tracd started.
   1. Open regedit.
   2. Go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Trac
   3. Create a new sub-key called Parameters
   4. Inside this new sub-key, create two new values:
   1. Application of type String. Set the value to the full path of python.exe. Eg C:\python25\python.exe
   2. AppParameters of type String. Set the value to C:\python25\Scripts\tracd-script.py --port 8009 C:\Trac\Slartibartfast - (note the change of port number, it's there for a reason we'll cover shortly).
5. Open the services tool from the Control Panel, find the Trac service and start it up! Navigate to http://localhost:8009 to make sure it still works.

If you get the same site as you did before, then all is going well. If not, then you revisit the steps to make sure you haven't missed anything out and that your pointing to the right location of the trac project.

Now that we know this works, we need to change the AppParameters value in the registry so that Trac fires up using the appropriate protocol. Edit the value, and append the following to the end of the existing value: --protocol=ajp - this forces the use of AJP. AJP's default port is 8009, which is why we chose this value in the first place.

Restart the Trac service. If you attempt to browse to the site now you won't get anything meaningful, but it's ready to be talked to from IIS, which brings us to the next step.

Server: Setting up Apache Tomcat ISS ISAPI Filter in IIS 6.

To get IIS to talk to Trac, we need to add an ISAPI filter that's able to translate to the AJP protocol. This is what we'll be doing in this section.

First, we prepare the filter for use:

1. Create a folder to store the ISAPI file. I called mine C:\AJPConnector.
2. Copy the Apache Tomcat AJP ISAPI filter (isapi_redirect-1.2.28.dll) into the folder you created in the previous step, and rename it to isapi_redirect.dll.
3. Create a new text file in the same folder called isapi_redirect.properties. Open the file with a text editor and add the following content:

   # Configuration file for the ISAPI Redirector
   
   # The path to the ISAPI Redirector Extension, relative to the website
   # This must be in a virtual directory with execute privileges
   extension_uri=/AJPConnector/isapi_redirect.dll
   
   # Full path to the log file for the ISAPI Redirector
   log_file=C:\AJPConnector\isapi_redirect.log
   
   # Log level (debug, info, warn, error or trace)
   log_level=info
   
   # Full path to the workers.properties file
   worker_file=C:\AJPConnector\workers.properties
   
   # Full path to the uriworkermap.properties file
   worker_mount_file=C:\AJPConnector\uriworkermap.properties
   

4. Create another new text file in the same folder called workers.properties. Open it, and add this content:

   # Define 1 real worker
   worker.list=trac
   # Set properties for trac (ajp13)
   worker.trac.type=ajp13
   worker.trac.host=localhost
   worker.trac.port=8009
   worker.trac.socket_keepalive=0
   

5. Create another new text file in the same folder called uriworkermap.properties. Open it and add the following:

   /Slartibartfast*=trac
   

   You'll notice that the project name is what I've used here. Down the track if you want more projects, you need to add more lines to this file.

Next we need to install the ISAPI filter in IIS so that it can get used. Feel free to do this on the default website if you like. I created another website in IIS running on a different port, but you don't have to. Any time I refer to the website I'm referring to the site you have decided to install the filter on.

We need to enable the filter as a web service extension first. To do that, we follow these steps:

1. Open up the IIS manager.
2. Right-click on "Web Service Extensions" and select "Add a new web service extension".
3. In the resulting dialog box, click the "Add..." button and specify the file C:\AJPConnector\isapi_redirect.dll. Click "OK".
4. Specify the name "AJPConnector" and click "OK".

Next we need to add the filter to the website.

1. In IIS manager right-click on the website and view the properties.
2. Select the "ISAPI Filters" tab.
3. Click "Add".
4. Give the filter the name "AJPConnector".
5. Specify the full path to the dll: C:\AJPConnector\isapi_redirect.dll.
6. Click "OK".
7. Click on the "Home Directory" tab.
8. Make sure the "Execute Permissions" is set to "Scripts and Executables".
9. Make a note of the application pool that the web site is running under! You'll need this in a minute.
10. Click "OK" to close the dialog.

For the ISAPI filter to function, we need to make sure that IIS has access to the folder which the binary is stored in. To do this we need to know which account the website is running under.

1. In IIS manager open the list of Application Pools.
2. Choose the application pool that your website is running under. Rick-click and select properties.
3. Click on the "Identity" tab. This will show you the name of the account that your site is running under.
4. Browse to C:\AJPConnector, right-click and select "Properties", then choose the "Security" tab.
5. Click "Add" and type in the name of the account that you found listed in the "Identity" tab in the application pool properties. You can also use the search feature if you want to.
6. When the user has been recognised, click "OK".
7. Select the user in the list at the top of the dialog, and make sure that they have "Full Control" selected in the list at the bottom.
8. Click on the "Advanced" button.
9. Select the check box that says "Replace permission entries on all child objects with entries shown here that apply to child objects". Then press "OK". This will apply the permissions to all child objects in the folder.
10. Click "OK" to close the dialog box.

You may have noticed that in the isapi_redirect.properties file we specified an extension_uri property. This property specifies the path to use to get to the isapi_redirect.dll file via IIS. Notice how it's also a relative path from the root folder. Hence we need to create a virtual directory which maps to the same path.

1. In IIS manager right-click on the website and select "New" then "Virtual Directory...".
2. Fill out the wizard making sure you use the name "AJPConnector" for the directory name, and point it at C:\AJPConnector. The site also needs to be able to execute programs, not just scripts.

Restart IIS. The quickest way to do this is to type iisreset into a command prompt or into the "Run" dialog.

It's best at this point to make sure that the ISAPI filter has been loaded. To do this, simply open up the IIS manager again and browser to the sites "ISAPI Filters" tab. If all is working, then you should see something like this:

Notice the green arrow. If it's red and pointing downwards, then something is wrong. You need to make sure you have followed the above steps correctly. Double-check the security of the folders and make sure executables are enabled on your site.

If all is well then we can test it! Make sure your Trac service is running, then open a browser and navigate to your local IIS website. You should see the Trac Project website for Slartibartfast appear in your browswer. Yay!

It's now very easy to change IIS to function over HTTPS instead of HTTP. That's beyond the scope of this article as there are hundreds of blog entries and how-tos out there already.

Server: Setting up CopSSH

This is the final step! We need to give people access to the Mercurial repositories over SSH. For that we need to set up a functional SSH server and give them access to the repository path. On the surface these both seem like easy jobs. Unfortunately setting up SSH servers on Windows isn't pleasant and pointing everyone's home folders at a certain repository is not something that comes out of the box in Windows.

What we need to do is use the CopSSH installer to help with the "easy" installation of SSH. Then we need to use a program like Junction to provdie symbolic-link style functionality to the user's folders.

First up, run the CopSSH installer program. Follow all of the prompts and feel free to use the default installation. That was easy wasn't it! It should install an SSH server service for you. I found it quite hard to locate in the Service Management dialog, but eventually found it under the name "Openssh SSHD".

CopSSH comes with utilities which help you manage users. Those utilities are all in the programs menu and are easy to use. For me, those utilities weren't enough, because I knew that I was going to have to make sure that the folder links were set up on creation of user accounts and removed when those accounts were deleted.

It's a good move at this point to download Junction, if you haven't already, and put it in an easy to reach location. Feel free to add it to it's own folder or to system32. It's up to you. I'll assume you've put it in C:\tools.

I then created two scripts. The first lets you add users. It looks like this:

REM AddUser.bat
"C:\Program Files\ICW\Bin\copsshadm.exe" --command activateuser --user %1 --shell /bin/bash --passphrase %2
C:\tools\junction.exe "C:\Program Files\ICW\home\%1\Slartibartfast" C:\Repos\Slartibartfast

The first line of this file executes the user activation feature of CopSSH. It creates a new user from a local security login (so the users need to be accessible in Active Directory or in the local security set up). It creates a home folder for them and also creates a public/private key pair which it stores in their home folder as well. The keys have the passphrase that is passed to the script on the command line and will be used by the users to SSH in and commit changes to the repository. The public key for the user is added to the server as a recognised key which can be used to log in so we don't have to specify it manually.

The second line of the script executes the Junction program and links a folder called "Slartibartfast", located in the user's home folder, to the folder where the repository is stored.

To execute the script simply run: adduser.bat [username] [passphrase].
Please note that during my testing, I wasn't able to use a passphrase that had spaces. This isn't due to a bug in the script. Even if you replace --passphrase %2 with --passphrase "%2" it still doesn't work. It also doesn't work in the user interface tools. This appears to be a bug in CopSSH. This isn't a big issue though, just make sure you don't have spaces in your passphrase and you should be fine.

The second script is for removing users, it looks like this:

REM RemUser.bat
C:\tools\junction.exe -d "C:\Program Files\ICW\home\%1\Slartibartfast"
"C:\Program Files\ICW\Bin\copsshadm.exe" --command deactivateuser --user %1

It's obvious what this does. First it removes the symbolic link in the user's folder, then it uses CopSSH's command line tools to remove them as a valid user from the SSH server.

Before you assume that everything at this point is ready to rock, you may need to make sure that your firewall is updated so that the SSH port, 22, is open.

Congratulations, you are now finished with the server set up. Now let's get the clients working. Before you go to the next step, make sure you add a user!

Client: Setting up PuTTy

The first bit is easy, make sure that you've installed the PuTTy program and added the install path to the system's PATH environment variable.

Take a copy of the user's private key. This is generated by CopSSH and should be sitting in the user's home folder on the server. The key is usually called [username].key. Put the key on your local machine. We need to convert this key into a format that PuTTy can use.

1. Fire up the puttygen.exe utility. It comes with the PuTTy program. Simply type "puttygen" into the Run dialog box and it should come up if you've added the install folder to the system PATH.
2. Click "Load" and select the private key file you copied from the server.
3. Enter the user's passphrase into the dialog that appears and press "OK".
4. You should get a message stating ...

   Successfully imported foreign key
   (OpenSSH SSH-2 private key).
   To use this key with PuTTY, you need to
   use the "Save private key" command to
   save it in PuTTY's own format.

   Just press "OK".

5. Click "Save private key" and save the key in a safe location on your machine.

Your key can now be used by PuTTy.

When using SSH, you are going to have to have to specify the passphrase each time you connect to the server. This can get annoying quickly especially if you do a lot of commits. Instead of typing this in manually every time, I prefer to use the pageant.exe utility that also comes with PuTTy. This takes charge of handling the key passphrase for you.

1. From the command line or Run dialog, type pageant. You see a rather bland dialog appear.
2. Click "Add key". Browse to the folder where you have stored your new .ppk (the PuTTy version of your key) and select the key.
3. When prompted, specify the passphrase and click "OK".
4. You should now see an item appear in the list box. This is your private key. Pageant is now in memory and handling that key.
5. Close pageant, but you should still see it running in the system tray.

I also find it helpful to add pageant.exe to my start-up folder so that it is always running when I log in to my machine. You may choose to do the same.

Client: Setting up Mercurial

If you haven't already, make sure you install Mercurial on the client machine using the default settings. Make sure you tell the installer to add the Mercurial path to the system PATH.

The last step of configuration for the client is to tell Mercurial to use the PuTTy tools when using SSH. Mercurial can be configured by a user-specific configuration file called .hgrc. On Windows it can also be called Mercurial.ini. The file is located in your home folder. If you don't know what your home folder is, simply open a command prompt and type echo %USERPROFILE% - this will tell you the path.

If you haven't set up your configuration yet, then chances are the configuration file doesn't exist. So you'll have to create it. Create a file call either .hgrc or Mercurial.ini in your home folder manually, and open it in a text editor. Here is what part of mine looks like:

[ui]
username = OJ Reeves

editor = vim
ssh = plink -ssh -i "C:/path/to/key/id_rsa.ppk" -C -agent

The last line is the key and this is what you need to make sure it set properly. We are telling Mercurial to use the plink program. This also comes with PuTTy and is a command-line version of what the PuTTY program itself does behind the scenes. We also add a few parameters:

• -ssh : Indicates that we're using the SSH protocol.
• -i "file.ppk" : Specifies the location of the private key file we want to use to log in to the remote server. Change this to point to your local putty-compatible ppk private key. Make sure you user forward-slashes for the path separators as well!
• -C : This switch enables compression.
• -agent : This tells plink to talk to the pageant utility to get the passphrase for the key instead of asking you for it interactively.

The client is now ready to rock!

Finale

It took a while, but we got there in the end. Let's give our new-found Mercurial SSH server a spin. This should be easy as opening a command prompt at the appropriate location on disk and typing:

hg clone ssh://url.to.your.server.com/Slartibartfast

If everything has been configured properly, you should see Mercurial create a local folder called Slartibartfast which contains the repository. Of course, there won't be much in it because you've only created it recently! But you should be able to start using Mercurial to commit changes and push the committed changesets to the server just by running hg push.

The End

It took a while to figure most of this stuff out despite the documentation that exists on the web. It also took a bit of time to write this up! I hope that someone out there finds it useful.

The funny thing about all this, is that despite the pain, I found it easier to set up than TFS!

Feedback is always wanted and welcome. I hope it helps

This is an issue when dealing with third-party libraries that are not signed. Sometimes you'll be lucky enough to be dealing with vendor that is happy to provide a set of signed assemblies, other times you won't. If your scenario fits the latter (as a recent one did for my colleagues and I), you need to sign the assemblies yourself. Here's how.

Note: delay signing is not covered in this article.

Scenario 1 - Foo and Bar

Foo is the component that you're building which has to be signed.
Bar is the third-party component that you're forced to use that isn't.

Grab Bar.dll and project along with Foo.dll and project to see a source sample.

You'll notice Foo has a .snk which is used to sign Foo.dll. When you attempt to compile Foo you get the following error message:

Assembly generation failed -- Referenced assembly 'Bar' does not have a strong name

We need to sign Bar in order for Foo to compile.

Step 1 - Disassemble Bar

We need to open a command prompt which has the .NET framework binaries in the PATH environment variable. The easiest way to do this is to open a Visual Studio command prompt (which is usually under the "Visual Studio Tools" subfolder of "Visual Studio 200X" in your programs menu). Change directory so that you're in the folder which contains Bar.dll.

Use ildasm.exe to disassemble the file using the /all and /out, like so:

C:\Foo\bin> ildasm /all /out=Bar.il Bar.dll

The result of the command is a new file, Bar.il, which contains a dissassembled listing of Bar.dll.

Step 2 - Rebuild and Sign Bar

We can now use ilasm to reassemble Bar.il back into Bar.dll, but at the same time specify a strong-name key to use to sign the resulting assembly. We pass in the value Foo.snk to the /key switch on the command line, like so:

C:\Foo\bin> ilasm /dll /key=Foo.snk Bar.il

Microsoft (R) .NET Framework IL Assembler.  Version 2.0.50727.1434
Copyright (c) Microsoft Corporation.  All rights reserved.
Assembling 'Bar.il'  to DLL --> 'Bar.dll'
Source file is ANSI

Assembled method Bar.Bar::get_SecretMessage
Assembled method Bar.Bar::.ctor
Creating PE file

Emitting classes:
Class 1:        Bar.Bar

Emitting fields and methods:
Global
Class 1 Methods: 2;
Resolving local member refs: 1 -> 1 defs, 0 refs, 0 unresolved

Emitting events and properties:
Global
Class 1 Props: 1;
Resolving local member refs: 0 -> 0 defs, 0 refs, 0 unresolved
Writing PE file
Signing file with strong name
Operation completed successfully

Bar.dll is now signed! All we have to do is reopen Foo's project, remove the reference to Bar.dll, re-add the reference to the new signed assembly and rebuild. Sorted!

Scenario 2 - Foo, Bar and Baz

Foo is the component that you're building which has to be signed.
Bar is the third-party component that you're forced to use that isn't.
Baz is another third-party component that is required in order for you to use Bar.

Grab Baz.dll and project, Bar.dll and project along with Foo.dll and project for a sample source.

When you attempt to build Foo you get the same error as you do in the previous scenario. Bear in mind that this time, both Bar.dll and Baz.dll need to be signed. So first of all, follow the steps in Scenario 1 for both Bar.dll and Baz.dll.

Done? OK. When you attempt to build Foo.dll after pointing the project at the new Bar.dll no compiler errors will be shown. Don't get too excited

When you attempt to use Foo.dll your world will come crashing down. The reason is because Bar.dll was originally built with a reference to an unsigned version of Baz.dll. Now that Baz.dll is signed we need to force Bar.dll to reference the signed version of Baz.dll.

Step 1 - Hack the Disassembled IL

Just like we did in the previous steps we need to disassemble the binary that we need to fix. This time, make sure you disassemble the new binary that you created in the previous step (this binary has been signed, and will contain the signature block for the strong name). Once Bar.il has been created using ildasm, open it up in a text editor.

Search for the reference to Baz -- this should be located a fair way down the file, somewhere near the top of the actual code listing, just after the comments. Here's what it looks like on my machine:

.assembly extern /*23000002*/ Baz
{
  .ver 1:0:0:0
}

This external assembly reference is missing the all-important public key token reference. Before we can add it, we need to know what the public key token is for Bar.dll. To determine this, we can use the sn.exe utility, like so:

C:\Foo\bin> sn -Tp Baz.dll

Microsoft (R) .NET Framework Strong Name Utility  Version 3.5.21022.8
Copyright (c) Microsoft Corporation.  All rights reserved.

Public key is
0024000004800000940000000602000000240000525341310004000001000100a59cd85e10658d
9229d54de16c69d0b53b31f60bb4404b86eb3b8804203aca9d65412a249dfb8e7b9869d09ce80b
0d9bdccd4943c0004c4e76b95fdcdbc6043765f51a1ee331fdd55ad25400d496808b792723fc76
dee74d3db67403572cddd530cadfa7fbdd974cef7700be93c00c81121d978a3398b07a9dc1077f
b331ca9c

Public key token is 2ed7bbec811020ec

Now we return to Bar.il and modify the assembly reference so that the public key token is specified. This is what it should look like after modification:

.assembly extern /*23000002*/ Baz
{
  .publickeytoken = (2E D7 BB EC 81 10 20 EC )
  .ver 1:0:0:0
}

Save your changes.

Step 2 - Reassemble Bar

This step is just a repeat of previous steps. We are again using ilasm to reassemble Bar.dll, but this time from the new "hacked" Bar.il file. We must use the exact same command line as we did previously, and we still need to specify the Foo.snk for signing the assembly. To save you having to scroll up, here it is again:

C:\Foo\bin> ilasm /dll /key=Foo.snk Bar.il

Microsoft (R) .NET Framework IL Assembler.  Version 2.0.50727.1434
Copyright (c) Microsoft Corporation.  All rights reserved.
Assembling 'Bar.il'  to DLL --> 'Bar.dll'
Source file is ANSI

Assembled method Bar.Bar::get_SecretMessage
Assembled method Bar.Bar::.ctor
Creating PE file

Emitting classes:
Class 1:        Bar.Bar

Emitting fields and methods:
Global
Class 1 Fields: 1;      Methods: 2;
Resolving local member refs: 3 -> 3 defs, 0 refs, 0 unresolved

Emitting events and properties:
Global
Class 1 Props: 1;
Resolving local member refs: 0 -> 0 defs, 0 refs, 0 unresolved
Writing PE file
Signing file with strong name
Operation completed successfully

Open up Foo's project, remove and re-add the reference to Bar.dll, making sure you point to the new version that you just created. Foo.dll will not only build, but this time it will run!

Disclaimer

"Hacking" third-party binaries in this manner may breach the license agreement of those binaries. Please make sure that you are not breaking the license agreement before adopting this technique.

I hope this helps!

In many colleges and univerties C++ is no longer taught as a core subject (along with Assembly language) which I find quite galling. It's a great language to learn, even if you never use it again. But the purpose of this post is not to preach the virtues and failures of the C++ language, but instead to talk about something that might aid those people who are using C++.

Anyone who's worked on a large C++ (or C) application has felt the pain of long build times. The first "big" C++ system that I worked on took 10 minutes to build. This was much bigger than anything I had experienced up until that point. Later in my career when I joined the games industry I really felt the pain of rebuilding a massive code base. The game took just under an hour to build from start to finish without any distributed compiling mechanism in place. When I finally got a copy of Incredibuild the build time dropped noticably, but not to a point where recompilation was an option every time I wanted it.

The solution that we implement: Unity builds (which I'll refer to as UB from now on because I'm lazy).

Now, a lot of C and C++ that have used these before might consider the idea of a UB to be a bit of a hack. I'm not sure if I agree or disagree. There is an air of "hackyness" about it, but it solves the problem of huge compile times on most platforms with most compilers.

Before I go into the definition, and give instructions on how to set up a UB, let me just state for the record that this isn't designed to replace normal builds for releasing code. The idea behind these is to dramatically reduce the build times for developers who are spending 8 hours a day modifying the code. Fixing bugs and adding enhancements generally means that a developer is constantly recompiling. Every time you compile, you have to wait (or perhaps entertain yourself in some way), and in waiting you are wasting precious time. Wasting time means a reduction in productivity. This can only be a bad thing. It's bad enough with short build times, but with long build times it becomes a huge problem. So please bear in mind that the normal release and product builds, builds that happen on automated build servers, etc, do not need to have a UB in place, they can continue to use normal builds.

The principle behind a UB is quite simple. It's all about reducing...

1. ... the number of times a file is opened.
2. ... the number of files that are opened.

In esssence, we're going to abuse the power of the preprocessor to do the above.

Every source file (.c, .cxx, .cc, .cpp, etc) that is compiled results in the creation of an object file. When all of the source files are compiled into object files, the linker then collects up all these object files and links them together into an executable application. For those of you who don't know: reading/writing to/from disk is the slowest thing you can do on a computer. Actually, it isn't so much the reading and writing, it's more the seeking. But the point remains the same. Disks are the only core parts of your system that have moving parts, so they're going to be slow! So if you want to speed things up, a good place to start is reducing I/O.

I don't want to turn this into a lesson on how C and C++ programs are compiled, so I'm going to cut to the chase. We know that the preprocessor parses each file before it's compiled which means that each file is going to be opened. When those parsed source files are then compiled, they're essentially opened again. Each of those files requires another seek. When the object file is generated, that's another seek. When the file is linked, that's another seek. There's lots of disk activity going on here!

If you haven't caught on yet, let me give you another hint. Each source file results in a couple of new files and a stack of seeks. We also have a neat preprocessor statement at our disposal (*cough* include *cough*).

That's right guys, we don't actually compile every file individually. We instead create a master file (or set of master files, depending on how big your source base is), which includes all of the other source files. This file (or set of files) is compiled instead.

To make it clear I'm going to show you the principle in action on a fake project in Visual Studio 2008. However, the principle can be applied regardless of the compiler and platform. Check out the screenshot on the left. This shows a standard C++ with a few files in it. Ordinarily each of those files will be compiled individually, and hence slowly.

The first step in creating a UB is to make a new project configuration which you can play with. Doing so will allow you to set up an area you can modify without breaking the "normal" project which will continue to be built as usual. So let's do that now. Create a new project configuration based on the debug build. See the following screenies:

When you've created the new configuration, make sure you have it set as the active configuration as shown on the right.

Then, you need to add a new file which will be the master UB file. I usually create a sub-folder in the project and add the file there. Both folder and file I tend to call UnityBuild.

When the file is created, the first thing we need to do is make sure that we edit the UnityBuild.cpp so that it includes all of the other files in the project. Check out the image for the example.

If we attempted to compile at this point, we have all kinds of issues. Everything right now is being included twice. So we need to fix that so that we don't have issues in every configuration. Let's start by fixing up the Unity build project. Select all of the source files except UnityBuild.cpp, and exclude them from the project (right-click on them to see the properties). Check out the pics below to see how it's done.

So that this point you've excluded the files from the UnityDebug configuration, and hence the unity configuration should build.

Note: if you're implementing this in a large existing source base you may find that the UB doesn't actually compile. You need to bear in mind that the preprocessor is making one large file out of all of your source files. Which means global variables, static variables, global functions, etc that appear more than once in the source code will now tread all over each other. Technically you shouldn't have this problem if you're writing "proper" code But the harsh reality is that lots of devs copy and paste code, duplicate function names, and all kinds of other horrible things. To get it working, you're going to have to do a bit of housekeeping! But since this is going to affect the source in a positive way, it can only be a good thing!

OK, next up let's get the other builds working again. You need to exclude the UnityBuild.cpp file from the build in both the Debug and Release builds (not the UnityDebug configuration). I won't show you how to do that, as it should be obvious. When you're done, you should see similar to the image on the left when you use the Debug or Release configurations from this point on.

You're done! The old builds should work just fine because your UB file isn't included in the configuration. Once you've sorted out the code duplication issues with the UB configuration, you should have a perfectly working configuration.

You may find that the whole process is much easier if you're building from the command line, especially using make on *nix machines, as you don't have to worry about excluding things from configurations. Instead, you just simply need to pass in a single file to the compiler - the UB file!

So after all that, what kind of improvements should expect to find? Well let me give you a few stats. When the UB was implemented at the game company I worked for, the build time dropped from 55 minutes to just over 6 minutes. When I implemented UB in a previous job the build time dropped from 10 minutes to less than 3 minutes. When I put them in place at home the build times dropped on average by 60%.

I'd be very surprised if you didn't notice a huge improvement in your build times if you use this mechanism.

Before I finish up, I need to highlight a few issues around housekeeping. As already stated, these builds are not used to replace the normal compilations. They should sit alongside to make it faster for the developer to do his or her work. This means that you need to make sure that both types of builds are working all the time. Keep your automatic builds using the normal build type, and you'll soon find out if you've not been maintaining your configurations properly.

Make sure that every time you add a new source file you exclude it from the UB configuration, and that you add it to the content of the UnityBuild.cpp file otherwise it won't be compiled and included in the build properly.

On the whole, UBs have really improved the speed in which I've been able to do things. My wait time for compilations is generally a third of what it was. That, in my view, is worth the "hack"

Thanks for reading!

PS. Please let me know of any typos, grammar errors, etc. It was a hefty post to put together and I might have missed a couple of obvious stuff-ups!

EDIT: I have fixed up a few grammar and spelling errors. Thank you Yoann and Bryce

Code quality and readability is something that isn't necessarily learned at University, nor is it something that can be mastered in a short period of time. It is something that anyone can learn. The main ingredients that are required are a bit of self-scrutiny, and the removal of the assumption that working code is the same as finished code.

Let me start by applauding Kirupa for the effort he puts into his posts, and the level of quality he achieves. This is by no means a stab at his work. I'm grateful that he's happy to discuss how his code can be improved. It's rare to find someone who's open to constructive criticism! Like me, he appears to be keen to learn from other people - if only there were more of those people around!

To avoid confusion, I think I should clarify exactly what I mean by "Unintuitive Code". In a nutshell, what I mean is: Code which fails to imply its purpose/functionality through poor use of language features, semantics, structure, naming conventions and natural language. Phew!

I'd like to share my thoughts on the steps that you can take to aid in writing more readable and maintainable code, developing interfaces to objects that are intuitive, and imply the right kinds of things with regards to the way the functions operate.

Solve the problem first

This doesn't mean write code! This means get a pen and paper, or a white board and a marker! Write down what you think the problem really is and break it into smaller chunks which can be broken down into a set of logical steps. When you give yourself a clearer understanding of what the problem is you'll increase the chance of writing more meaningful code with a much clearer interface.

When you've broken the problem down into smaller chunks, it's highly likely you'll then find issues that you wouldn't have seen or considered if you'd just fired up your code editor first. This is good because you've now got a greater understanding of the problem space, and can now create a more meaningful and appropriate code architecture while keeping in mind the issues that you've already stumbled across. The amount of "coding in the dark" you have to do has already been minimised.

At this point you've already prevented the need to refactor your code before you've even finished the first iteration. Your interfaces will be cleaner, and the number of 'hacks' that you'll have to put in to fix things you hadn't initially thought of will be substantially reduced. Don't underestimate how valuable a bit of up-front analysis and design can help with keeping your code clean.

Once you're done with improving your understanding of the problem space, you're ready to open your editor and start writing code. Writing defensively from the start is a good idea, particularly if the code is going to end up being maintained by someone else.

Write your first iteration

Put your ideas down in code. Try your best to make an intuitive model, using concrete objects where applicable, trying your best to reduce coupling, and separating implementation from interface. While this is a key phase, it's not as key as the next one! Make sure that when you're done writing your first version, you prepare yourself to be happy to rip out a large portion of what you write - because you're going to be replacing it with something better.

Call a spade a spade

If you want the marks, state the bloody obvious! That is, your funtions should state exactly what they do. I'm not suggesting that you have function names like GetAReferenceToTheNormalVectorAndUseItToCalculateTheLightingForThePolygon() as that's a bit over the top. Try to avoid names like DoStuff(), ProcessData(), DoEvents() (yes, that's a stab at you, Microsoft) and GetDoohicky(). Names like CalculateLighting() and GetNormal() are descriptive enough and do a good job of implying their function. Don't mislead the user of your class by using names that quite clearly suck.

Review your interfaces and functions

There's a strong possibility that even though you've put a great deal of thought into your solution, you've still managed to imply certain things that you didn't necessarily mean.

The interface to an object and the signature of your functions can (and should) say more about your code than you think. So ask yourself the following:

• Does your object name reflect the functionality that it encapsulates?
• Does the function imply operations that don't happen?
• Does the function not imply functions that do happen?
• Is the function's name descriptive of the type of function that it actually is?
• Does your function return a meaningful value based on the context?
• Does your function require intuitive parameters for it to function?
• Is the parameter list as minimal as possible without affecting the functionality?

I'm sure there are more, but I can't think of them off the top of my head.

When you've finished with your review, ask someone else to have a read of it. Ask them to give you a brief overview of your classes/functions as if you didn't know the code and they did. If they give a pretty good picture of what the object does, then you've done well. If they can't tell you what goes on at a high-level then you'll have to go through another review iteration.

Add comments that clarify, and remove comments that don't

I'm almost certain that every maintenance coder on the planet has been faced with the nasty combination of confusing code and invalid comments. It not only doesn't help, it makes things worse. Here is an example of a "WTF comment":

/* this class handles date formats */
class Profile
{
  // code goes here
};

If you didn't say "WTF!?" to the above code, then please go to the start of this post, and reread!

Iterate

Make sure that you don't stop working when the code starts working. Working code is not the same as finished code. Keep reviewing your work. Look for possible improvements. Be critical of your own work. Treat your own code as if it was someone else's and treat the task as though the result is going to be shown to a stack of other developers.

Be receptive to post-release feedback

When your code gets used by other people, you'll end up with more suggestions and possible tweaks to make it less unintuitive. Don't be ignorant, even if the suggestions are petty. Take them on board and see if you can utilise those bits of feedback to aid in production of even better quality code!

Good luck

The intent of this post is to cover that side of the argument. How do you give a meaningful answer to a well constructed question?

I'd like to start by sharing an example of a recent forum thread that I saw which highlights the issue nicely.

Asker: I've recently been given the task of creating a C++/Win32 version of application appname. Unfortunatley I've never written any Win32 code before, so I need a few pointers to get started. Can someone please show me an example how to create a Window using Win32 and C++?

Answerer 1: Download .NET and use managed C++ to create your form.

Answerer 2: I use allegro for everything, and I think it's great. Download allegro and use the tutorials.

Answerer 3: Managed DirectX extensions make it easy to GUIs, try using that.

Answerer 4:Using Win32 is a pain, why are you using it? Why not use Java?

Answerer 5: If you're going to use a graphics API then you're better off using something like SDL which is cross-platform.

Is it just me, or are all of those answers total and utter shit?

The bloke who asked the question clearly wanted an example of window creation using the Win32 API and C++. What did he get in response? Recommendations for 5 other technologies that people like to use for their own projects. Not one meaningful answer.

As far as I'm concerned this is the same as having someone ask "I'm really in the mood for fish and chips, does anyone know a good shop to get some?" and have a few people respond with "Well, if you're going to eat food, then you should consider a Thai Green Curry with Lamb" or "When I eat, I like to have lots of sugar. So go to Dreamy Donuts, and try the super heart-stopping, 3-hour-old, artery-blocking cardboard donut. It's fantastic!". WTF has that got to do with fish and chips?!

One of the universal issues we face is the fact that people do not have the ability to read the question. It's something that people have had a problem with since the early days of school. They fail to read the question properly, and instead come up with their own version of the question that isn't the same, and hence their answer is poor.

In the case of coders, there's a bit more to it. People like to preach and evangelise technology, languages or applications that they like to use, as it makes them feel good. Most people like to push form threads and conversations towards a topic they consider themselves to be experts in because it gives them the chance to get on a soap box.

Now, I'm not going to say that I don't get on a soap box, because I quite clearly do! But the point I'm trying to make is that people who ask specific questions deserve specific answers. So here are my rules of thumb for answering peoples questions.

1. Read the question. Then read it again. There is no way you're going to be able to give a meaningful answer to a well constructed question without fully understanding what's being asked. Try to adhere to the golden rule of answering questions: If all else fails, READ THE QUESTION.
2. Answer the question, but don't post the response. Answers to questions are like solutions to problems in development. Your first iteration is going to be a solution, but it's not going to be the best solution. Reread your answer. Scrutinise it. Look for as many holes as you can find. Any that you miss will be picked up by someone else!
3. Rewrite your answer. After you've answered, and you've found the holes. You'll no doubt have to rewrite it. Make sure you use grammar, punctuation and well constructed sentences. Try to keep sentences as short as possible. Be as clear as you can without being verbose. Provide examples of code or references to cases where your view has worked in the past. Provide links to documentation to support your answer.
4. Direct your answer at the question! Make sure that your answer does actually answer the question. Make specific references to the parts of the question that you're answering and point out how it's of benefit, or how it actually relates to the problem.
5. Don't evanglise your favourite technology. If you come across as an evangelist, then people will tend not to take your response seriously. It's easy to see whether someone has an open view, or whether they're biased towards something they have a passion for. Don't be a preacher!
6. Don't answer if you don't know! Lots of people seem to put their $0.02 into the conversation even if they don't know what they're talking about. It's quite simple: if you don't know the answer, do not respond to the question. You won't be adding anything of value to the discussion and you'll end making yourself look stupid. Instead, you should monitor the thread and wait for someone else to respond. Chances are you'll end up learning something!

Thoughts?

Creating concrete data objects/classes is a good thing to do, as it reduces the probability of bugs, and crazy side-effects. It's also an important first step in writing intuitive code - which will be the topic of a later blog post.

I'd like to quote one of my lecturers that I learned from during my time at UTS...

If in doubt, do as the ints do.

I realise the meaning of this point isn't obvious on the surface, but with some example code it'll all become clear.

An example concrete data type - a 3D Vector class

Let's say you're writing some code to do some 3D rendering, and you're in need of a class that can handle the functionality and behaviour of Vectors in 3D space. The first and most obvious thing that you need to handle are x, y and z coordinates. Let's start with a very basic Vector3 class:

class Vector3
{
public:
  float X;
  float Y;
  float Z;
};

At this point you've got an object that gives public access to its internal workings. Can we say that's what the int datatype does? Are you able to mess around with its inner workings? No, you're not. Not just that, but the idea of public member variables breaks the whole notion of encapsulation/information hiding. We need to hide the internal workings, but in doing so we remove the ability to set and get the values on the object. We need to expose some functions that will allow us to do that. Our improved version of the code might look like this:

class Vector3
{
private:
  // change the variable names to make it obvious that
  // they are member variables, not local or global.
  float m_X;
  float m_Y;
  float m_Z;
 
public:
  // getters
  float GetX();
  float GetY();
  float GetZ();
 
  // setters
  void SetX( float x );
  void SetY( float y );
  void SetZ( float z );
};

This is an improvement, as we now have control over the inner workings of the object without exposing the implementation to external classes. Now let's say that we want to be able to construct a new Vector3 object through a variety of ways, ie. in exactly the same way we can with int. For example:

// this is what we can do with ints:
int a( 1 );
int b = a;
int c( b );
int d, e;
d = e = c;
 
// we want do the same kind of things with our
// own class
Vector3 a( 1.0, 0.0, -1.0 );
Vector3 b = a;
Vector3 c( b );
Vector3 d, e;
d = e = c;

We need to expose some options for construction and assignment. So our next iteration might look like this:

class Vector3
{
private:
  // change the variable names to make it obvious that
  // they are member variables, not local or global.
  float m_X;
  float m_Y;
  float m_Z;
 
public:
  // construction - default to zero if nothing is passed in
  Vector3( float x = 0.0, float y = 0.0, float z = 0.0 );
  Vector3( Vector3& v );
 
  // assigment operator
  void operator=( Vector3& v );
 
  // getters
  float GetX();
  float GetY();
  float GetZ();
 
  // setters
  void SetX( float x );
  void SetY( float y );
  void SetZ( float z );
};

The above interface should do what we need it to... or should it? A more careful examination will reveal that it doesn't actually behave exactly as you'd expect. The copy constructor takes a reference to another Vector3, which could be modified inside the copy constructor. We have the same issue with our assignment operator. Integers do not behave this way, so we need to modify our interface a bit more to tidy it up:

class Vector3
{
private:
  // change the variable names to make it obvious that
  // they are member variables, not local or global.
  float m_X;
  float m_Y;
  float m_Z;
 
public:
  // construction - default to zero if nothing is passed in
  Vector3( float x = 0.0, float y = 0.0, float z = 0.0 );
  Vector3( const Vector3& v );
 
  // assigment operator
  void operator=( const Vector3& v );
 
  // getters
  float GetX();
  float GetY();
  float GetZ();
 
  // setters
  void SetX( float x );
  void SetY( float y );
  void SetZ( float z );
};

We've now made sure that the Vector3 class does not modify anything that doesn't belong to it, which again is how the integers behave. But there is still something missing. The assignment operator doesn't allow for chaining (eg. int a = b = c = d;) just like the ints do, so we need to make a slight adjustment to the overload:

// return a const reference to ourself
const Vector3& operator=( const Vector3& v );

There, much better.

We're now at the stage where we want to be able to add/subtract/multiply/divide vectors together, but before we start overloading the operators we should look at the way integers behave when they go through the same operations:

int a, b, c, d;
a = b; // b doesn't change, a does.
a * b; // both a and b do not change.
a = b * c; // both b and c do not change, but a does.
a = ( b + c ) * d; // a is the only thing that changes
a += b / c; // again, a is the only thing that changes.

It's obvious from this that when we overload the operators, we only modify the content of the object if it is on the left hand side of one of the assignment operators. Our interface should make this obvious:

class Vector3
{
private:
  // change the variable names to make it obvious that
  // they are member variables, not local or global.
  float m_X;
  float m_Y;
  float m_Z;
 
public:
  // construction - default to zero if nothing is passed in
  Vector3( float x = 0.0, float y = 0.0, float z = 0.0 );
  Vector3( const Vector3& v );
 
  // assigment operators - not const because the current object
  // needs to change
  const Vector3& operator=( const Vector3& v );
  const Vector3& operator+=( const Vector3& v );
  const Vector3& operator-=( const Vector3& v );
  const Vector3& operator*=( const Vector3& v );
  const Vector3& operator/=( const Vector3& v );
 
  // other operators - all const functions to make sure that the
  // internal state of the object doesn't get modified when the
  // function is called. Separate temporary instances of Vector3
  // objects are created and  returned when executed.
  Vector3 operator+( const Vector3& v ) const; // v1 + v2
  Vector3 operator-( const Vector3& v ) const; // v1 - v2
  Vector3 operator/( const Vector3& v ) const; // v1 * v2
  Vector3 operator*( const Vector3& v ) const; // v1 / v2
 
  // getters
  float GetX();
  float GetY();
  float GetZ();
 
  // setters
  void SetX( float x );
  void SetY( float y );
  void SetZ( float z );
};

The class is starting to take shape, but there are some other functions missing that are an integral part of any Vector class: normalise(), dot() and cross().

The normalise function is used to create a unit vector (ie. a vector with a length of 1.0). But the question here is: when calling the function, should the object be modified, or should it return a copy of the Vector with a unit length? Let's look at the difference in function signatures:

// this function would modify the object directly
void Normalise();
// this function would return a new vector that is normalised
Vector3 Normalise() const;

Making a decision like this can be a bit of a pain in the butt, but we're fortunate in this case because we can deduce what should be done! Generally when dealing with normalised vectors, we tend to retain a reference to the normal while dealing with a stack of other vectors. So another instance of a vector is used alongside the other vectors. Let's look at how this might be done with both above functions if we had a vector that we wanted to reuse, but get a normalise version of at the same time:

// this is the vector we want to keep as is, but need a
// normalised copy of
Vector3 someVector;
 
// here's how we'd do it with the first option:
Vector3 normal1 = someVector;
normal1.Normalise();
 
// here's how we'd do it with the second option:
Vector3 normal2 = someVector.Normalise();

In my view, the second option is easier to read, and is a bit more intuitive. Not just that, but it's less code! So based on this, we'll utilise the second version of the function. Our class now looks like this:

class Vector3
{
private:
  // change the variable names to make it obvious that
  // they are member variables, not local or global.
  float m_X;
  float m_Y;
  float m_Z;
 
public:
  // construction - default to zero if nothing is passed in
  Vector3( float x = 0.0, float y = 0.0, float z = 0.0 );
  Vector3( const Vector3& v );
 
  // assigment operators - not const because the current object
  // needs to change
  const Vector3& operator=( const Vector3& v );
  const Vector3& operator+=( const Vector3& v );
  const Vector3& operator-=( const Vector3& v );
  const Vector3& operator*=( const Vector3& v );
  const Vector3& operator/=( const Vector3& v );
 
  // other operators - all const functions to make sure that the
  // internal state of the object doesn't get modified when the
  // function is called. Separate temporary instances of Vector3
  // objects are created and  returned when executed.
  Vector3 operator+( const Vector3& v ) const; // v1 + v2
  Vector3 operator-( const Vector3& v ) const; // v1 - v2
  Vector3 operator/( const Vector3& v ) const; // v1 * v2
  Vector3 operator*( const Vector3& v ) const; // v1 / v2
 
  // getters
  float GetX();
  float GetY();
  float GetZ();
 
  // setters
  void SetX( float x );
  void SetY( float y );
  void SetZ( float z );
 
  // helpers
  Vector3 Normalise() const;
};

So, next up we need the dot() function, which gives us the dot product of two vectors. The dot product is a single value which represents the angle between the two vectors, so that's what the function should return. Since the dot product requires two vectors, it would make sense for the function to be given a reference to the secont vector that is part of the dot product equation. None of the objects should be modified at all during the course of the function, so we should make that obvious in the function signature. Our class now looks like this:

class Vector3
{
private:
  // change the variable names to make it obvious that
  // they are member variables, not local or global.
  float m_X;
  float m_Y;
  float m_Z;
 
public:
  // construction - default to zero if nothing is passed in
  Vector3( float x = 0.0, float y = 0.0, float z = 0.0 );
  Vector3( const Vector3& v );
 
  // assigment operators - not const because the current object
  // needs to change
  const Vector3& operator=( const Vector3& v );
  const Vector3& operator+=( const Vector3& v );
  const Vector3& operator-=( const Vector3& v );
  const Vector3& operator*=( const Vector3& v );
  const Vector3& operator/=( const Vector3& v );
 
  // other operators - all const functions to make sure that the
  // internal state of the object doesn't get modified when the
  // function is called. Separate temporary instances of Vector3
  // objects are created and  returned when executed.
  Vector3 operator+( const Vector3& v ) const; // v1 + v2
  Vector3 operator-( const Vector3& v ) const; // v1 - v2
  Vector3 operator/( const Vector3& v ) const; // v1 * v2
  Vector3 operator*( const Vector3& v ) const; // v1 / v2
 
  // getters
  float GetX();
  float GetY();
  float GetZ();
 
  // setters
  void SetX( float x );
  void SetY( float y );
  void SetZ( float z );
 
  // helpers
  Vector3 Normalise() const;
  double Dot( const Vector3& v ) const;
};

Note that the function is marked as const to imply that the object will not have a different state when it's called, and the parameter is a const reference to imply that the parameter will not be modified as well.

Finally, we need a function which will determine the cross product of two vectors (commonly used to determine the vector that is perpendicular to two input vectors. The cross product equation takes two vectors and results in another vector, which again implies that the two input vectors do not change. Based on this implication, our function signature should be easy to deduce. While we're there, let's just chuck in a cheeky length() function which will give us the magnitude of the vector. Our class now looks like this:

class Vector3
{
private:
  // change the variable names to make it obvious that
  // they are member variables, not local or global.
  float m_X;
  float m_Y;
  float m_Z;
 
public:
  // construction - default to zero if nothing is passed in
  Vector3( float x = 0.0, float y = 0.0, float z = 0.0 );
  Vector3( const Vector3& v );
 
  // assigment operators - not const because the current object
  // needs to change
  const Vector3& operator=( const Vector3& v );
  const Vector3& operator+=( const Vector3& v );
  const Vector3& operator-=( const Vector3& v );
  const Vector3& operator*=( const Vector3& v );
  const Vector3& operator/=( const Vector3& v );
 
  // other operators - all const functions to make sure that the
  // internal state of the object doesn't get modified when the
  // function is called. Separate temporary instances of Vector3
  // objects are created and  returned when executed.
  Vector3 operator+( const Vector3& v ) const; // v1 + v2
  Vector3 operator-( const Vector3& v ) const; // v1 - v2
  Vector3 operator/( const Vector3& v ) const; // v1 * v2
  Vector3 operator*( const Vector3& v ) const; // v1 / v2
 
  // getters
  float GetX();
  float GetY();
  float GetZ();
 
  // setters
  void SetX( float x );
  void SetY( float y );
  void SetZ( float z );
 
  // helpers
  Vector3 Normalise() const;
  double Dot( const Vector3& v ) const;
  double Length() const;
  Vector3 Cross( const Vector3& v ) const;
};

The interface to our class now looks fine.. except for one small omission. Const objects are read-only objects, and hence reading values from a const object should be legal. On the flip side, when we read a given x, y, or z value from a vector the vector shouldn't be modified at all. So with that in mind, we should mark each of the getter function as const as well:

class Vector3
{
private:
  // change the variable names to make it obvious that
  // they are member variables, not local or global.
  float m_X;
  float m_Y;
  float m_Z;
 
public:
  // construction - default to zero if nothing is passed in
  Vector3( float x = 0.0, float y = 0.0, float z = 0.0 );
  Vector3( const Vector3& v );
 
  // assigment operators - not const because the current object
  // needs to change
  const Vector3& operator=( const Vector3& v );
  const Vector3& operator+=( const Vector3& v );
  const Vector3& operator-=( const Vector3& v );
  const Vector3& operator*=( const Vector3& v );
  const Vector3& operator/=( const Vector3& v );
 
  // other operators - all const functions to make sure that the
  // internal state of the object doesn't get modified when the
  // function is called. Separate temporary instances of Vector3
  // objects are created and  returned when executed.
  Vector3 operator+( const Vector3& v ) const; // v1 + v2
  Vector3 operator-( const Vector3& v ) const; // v1 - v2
  Vector3 operator/( const Vector3& v ) const; // v1 * v2
  Vector3 operator*( const Vector3& v ) const; // v1 / v2
 
  // getters
  float GetX() const;
  float GetY() const;
  float GetZ() const;
 
  // setters
  void SetX( float x );
  void SetY( float y );
  void SetZ( float z );
 
  // helpers
  Vector3 Normalise() const;
  double Dot( const Vector3& v ) const;
  double Length() const;
  Vector3 Cross( const Vector3& v ) const;
};

We're done! Our class looks complete (enough), so let's pump out a definition for the functions (just for the sake of clarity).

Vector3::Vector3( float x, float y, float z )
: m_X( x ),
  m_Y( y ),
  m_Z( z )
{
  // don't need to do anything in the body of the
  // function because we're using the initialisation
  // lists instaed.
}
 
Vector3::Vector3( const Vector3& v )
: m_X( v.m_X ),
  m_Y( v.m_Y ),
  m_Z( v.m_Z )
{
  // don't need to do anything in the body of the
  // function because we're using the initialisation
  // lists instaed.
}
 
const Vector3& Vector3::operator=( const Vector3& v )
{
  // check for self-assignment
  if( this != &v )
  {
    m_X = v.m_X;
    m_Y = v.m_Y;
    m_Z = v.m_Z;
  }
 
  // return a reference to ourselves for chaining
  return *this;
}
 
const Vector3& Vector3::operator+=( const Vector3& v )
{
  m_X += v.m_X;
  m_Y += v.m_Y;
  m_Z += v.m_Z;
 
  return *this;
}
 
const Vector3& Vector3::operator-=( const Vector3& v )
{
  m_X -= v.m_X;
  m_Y -= v.m_Y;
  m_Z -= v.m_Z;
 
  return *this;
}
 
const Vector3& Vector3::operator*=( const Vector3& v )
{
  m_X *= v.m_X;
  m_Y *= v.m_Y;
  m_Z *= v.m_Z;
 
  return *this;
}
 
const Vector3& Vector3::operator/=( const Vector3& v )
{
  m_X /= v.m_X;
  m_Y /= v.m_Y;
  m_Z /= v.m_Z;
 
  return *this;
}
 
Vector3 Vector3::operator+( const Vector3& v ) const
{
  return Vector3( m_X + v.m_X, m_Y + v.m_Y, m_Z + v.m_Z );
}
 
Vector3 Vector3::operator-( const Vector3& v ) const
{
  return Vector3( m_X - v.m_X, m_Y - v.m_Y, m_Z - v.m_Z );
}
 
Vector3 Vector3::operator/( const Vector3& v ) const
{
  return Vector3( m_X / v.m_X, m_Y / v.m_Y, m_Z / v.m_Z );
}
 
Vector3 Vector3::operator*( const Vector3& v ) const
{
  return Vector3( m_X * v.m_X, m_Y * v.m_Y, m_Z * v.m_Z );
}
 
float Vector3::GetX() const
{
  return m_X;
}
 
float Vector3::GetY() const
{
  return m_Y;
}
 
float Vector3::GetZ() const
{
  return m_Z;
}
 
void Vector3::SetX( float x )
{
  m_X = x;
}
 
void Vector3::SetY( float y )
{
  m_Y = y;
}
 
void Vector3::SetZ( float z )
{
  m_Z = z;
}
 
Vector3 Vector3::Normalise() const
{
  double length = Length();
  if( length == 0.0 )
  {
    // return a zero vector if it's got zero length
    return Vector3();
  }
  double invLength = 1.0 / length;
  return Vector3( m_X * invLength, m_Y * invLength, m_Z * invLength );
}
 
double Vector3::Dot( const Vector3& v ) const
{
  return  m_X * v.m_X + m_Y * v.m_Y + mZ * v.mZ;
}
 
double Vector3::Length() const
{
  return sqrt( m_X * m_X + m_Y * m_Y + mZ * mZ );
}
 
Vector3 Vector3::Cross( const Vector3& v ) const
{
  return Vector3( m_Y * v.m_Z - m_Z * v.m_Y,
                  m_Z * v.m_X - m_X * v.m_Z,
                  m_X * v.m_Y - m_Y * v.m_X );
}

Now that we have a functional class, we should have no problem using it in all of the above scenarios without any crazy side-effects. The class should be concrete!

Disclaimer: This code hasn't been compiled, and might not run without a few tweaks. I wrote this off the top of my head while sitting in front of the TV! Comments, questions and flames are welcome.

Help!!
I need somebody...
Help!
Not just any body...
Help!
You know I need someone...
HEEEELP!

I have lost count of the times I've heard this (and not just when playing The Beatles). In fact, to be honest, I never kept count, but I know it's a lot.

On a daily basis I lose a fair bit of time helping my workmates. I get asked for help while I'm on IM from various "students" and friends I have around the web. I also get to help out family and friends on a regular basis face to face when I vist them or they visit me. I'm basically a constant source of solutions for I.T. and development related problems.

This is something I like! I enjoy helping people solve their problems. I enjoy helping them learn about something they don't know enough about. I like to see them take their new knowledge and apply it to other problems. It's a very satisfying experience.

But there is one problem. The questions. For some reason, most people don't seem to think too hard before they speak, and the questions they are ask so esoteric, vague and/or broad that it's close to impossible to give a meaningful answer. This post is about those questions! The target of this post is anyone who needs to ask for help - geeks, non-geeks, students, etc. This will also help those who, on more than one occasion, have asked for help and received none.

An example of a bad question

Oliver, I have an issue with my code. It isn't adding the item to the list when a button is clicked, what's wrong?

Some of you might argue that this a fair question, and I'll agree, it is a fair question. But what it lacks is context.

My response to the above question was:

OK, there are quite a few answers to the question, so can you please clarify a few things for me so I can give you a meaningful answer:

• What is "it"?
• What is the "item"? Is it a primitive type, or a class you've created?
• Is the application a fat-client app, or a web application?
• Which button are you clicking?
• ...etc

You get the idea. I could have answered straight away with a massive rant about the possible reasons why a given scenario results when a button is pressed, but no doubt it would have been a huge waste of time. Instead, I went for the other option, which was to get a better idea of the problem. After a bit of a digging around, it turns out that the above question should have been:

Oliver, I have an issue with my web form application. When I press the 'add' button, it is supposed to create a new instance of type Mytype, add that new instance to a collection that is stored in the session, and then post back with the data table populated with the new list of items. When I press the button, the application posts back, but the contents of the list doesn't change. Do you have any idea what's wrong?

Man what a difference that made!

The essence of getting a good answer to a question is to make sure that the question is a good question in the first place.

An example of a not-so-bad-but-could-be-better question

hey, any idea where i could get an example html for world timezones? pref with country/region and offset?

Now this certainly isn't bad, and it is possible to deduce the intended meaning of the question from the question! But it turns out that the question should have been:

hey, do you have any idea where i could get a list of timezones mapped to cities/countries which I can use inside a <select> tag in HTML?

The art of meaningful question construction

You wouldn't think that this could be considered an 'art', but it is. I'm sure there are lots of people out there who have written up a question on a programming forum only to find that it is totally ignored. Nobody responds, and your post simply makes it way to the bottom of the forum pile regardless of the number of times you bounce it to the top again. If this happens, you've asked a shit question. It's that simple.

There are only a few subtle yet important differences that make a question bad instead of good:

1. Assumed knowledge. 9 out of every 10 questions that are asked are ruined by the fact that the asker assumes that the answerer knows enough about the problem space to just belt it out without too much difficulty. Well, here's a newsflash: they don't!. People who are spending time on forums, or at work, helping people solve their problems require more than just a generic set of information to be able to answer the question properly. In my view, you should always do what my old high-school English teacher told me before going into my final exams: "To get the marks, state the bloody obvious!". Thank you Mrs Price, you're dead right. Too much information on the topic is better than not enough. So be forthcoming, don't assume that the person you're asking is already in the loop.
2. Vague terminology. In short, don't use words that don't make sense, that are vague, or that don't add to the meaning. Some examples are: it, item, object, doohicky, thingy, whatsit, dooverlacky, thingamajig, woozit, etc. Be specific. Be direct. Be helpful!
3. Specific terminology. This is the total opposite to the previous point. Don't bombard someone with jargon, large words, and acronyms. Eg. instead of saying that you've broken your pre-regulation destroyer-class solid-fuel recoil booster you should instead use the word spring. Large words won't make you look smart, they'll just piss people off and prevent you getting the help you need.
4. Give a good example. A lot of the time, the problem that you have is one that's come about from being in the depths of your code. If you can, break it out into a separate application, or "spike" as they like to call it in an Agile world, and demonstrate the issue in a much cleaner environment/situation. You're more likely to receive help if you post a snippet of code than if you dump your entire application in source form on a forum.
5. Think before you speak. You're in a rush. We know that. Everyone's always in a rush. People tend to jump headfirst into a question without really thinking about what they're asking, and it doesn't benefit them or the person they're speaking to. Take that extra 10 seconds to think about what it is you actually need to ask. When you're able to word in such a way that almost anyone would be able to understand you without prior knowledge, your question is ready to be asked.
6. Keep it as short as possible without losing information. Yes, this point slightly contradicts the point I made earlier about too much information being better than not enough. But the point is that you needn't be verbose. Keep it as short as you can, but make sure you've got enough information out to make things clear. Pages and pages of text, and/or a 10 minute ear-bashing is enough to put anyone off helping you.
7. Do a bit of research first. This is more for those technical problems than anything, but the rule does generally apply to anything. Chances are that someone else out there has had the same problem as you. It's highly likely that the problem has been solved, and there is information out there which is freely available should you make an effort to seek it out. If you can't find it after a few minutes of searching, then get your thoughts together and write up a decent question. One guaranteed way of pissing someone off is to ask them a question which can be answered by the first result of a basic a Google search. Make the effort to help yourself before you take up someone else's time.
8. Try to solve the problem yourself first. This will not only give you a better understanding of the problem, but it will show that you've actually made an effort to solve the problem rather than just getting someone else to do your homework for you.
9. Be polite. Be rude, be blunt, be expecting, and you'll be ignored (and rightly so). Don't expect help from people if you're not going to be courteous and/or use manners. If you get help, express appreciation. If someone takes the time to respond to get clarification on your problem, again you should make it obvious that you are grateful. They're on your side, so try and keep them there.
10. Look at the question from the perspective of the listener. This is probably the most important point. While writing your question ask yourself:
    • Do they know what *BLAH* actually is?
    • Do they need to know what *BLAH* actually is?
    • Are they aware of the environment I'm working in?
    • Would they need to know your hardware specs?
    • Should they be made aware of the language you're using?
    • Is there enough context in my question to remove confusion?
    • Is there evidence of the fact that I've tried to solve the problem myself?

    ..the list goes on.

11. Post a meaningful title. Again this applies in the online world when posting to forums. If you're going to write a post to ask for help, give some context to your problem in your post heading. Here are some things that you should avoid:
    • HELP!! URGENT HELP REQUIRED!!
    • Stupid homework problem
    • Why won't this work?
    • I have 15 mins to finish this.. plz help!
    • GIVE ME HELP NOW!

    You don't have to be a rocket scientist to know why those titles are bad. Most regular forum users will just skip your post, and the moderators will probably tear you a new a**eshole for being stupid. Instead, try something like the following:

    • Memory allocation problem using malloc() in C++
    • CSS problem with IE, works in Firefox

    These kinds of topic headings are going to not only help give context, but will most likely attract people who are experts in those respective areas.

Questions that should never be asked

There are some questions that should never, ever be asked.

• How do I write Quake XVI? You don't. You're not smart enough.
• How do I stop my console program from disappearing when it finishes? Ask Google.
• Where can I download *insert application name*? You don't. Go and buy it.
• How do I hack into Hotmail? The authors of Hotmail are much smarter than you. Instead, go outside and look at something shiny.
• Can you do my homework for me? Errr.. no.

...etc.

A final thought...

Most of the time, people who give a great deal of thought to a problem before asking for someone's help end up solving the problem themselves. You may find that before you even get to voice your question, the answer becomes clear because you've put effort into defining your question!

As a general overview, a Game Geek is a geek who has strong knowledge in most areas of gaming technology, understands the bits of the computer which make games run and run fast, and is aware of a plethora of gaming sites which he/she can use to make sure they're up to date with what's coming out, when, and what's hot. So let's go into a bit more depth...

1. Know your game types. There are many types of games out there, not just the standard FPS or RPG. Read up on the various categories of games, and understand the differences.
2. Know the guts of a game. Games are very hard to build! The developers of games are really on the cutting edge of technology and making the most of the hardware is a very difficult task from a development perspective. Read up on the major components of a game (eg. engine, graphics, artificial intelligence, physics, etc). Learn to appreciate the effort that goes into creating the worlds that you explore when you create them.
3. Get involved in an online clan. Many online games allow team play, and becoming part of a regular group (or clan) is a good way of learning more about the game, and becoming a better team player.
4. Learn the difference between fixed-function TNL, vertex shaders and pixel shaders. Back in the good old days before graphics hardware became what it is at the moment, games developers were stuck working with a fixed-function transform and lighting (TNL) pipeline. This didn't give a great deal of flexibility when outputting funky graphics. These days we have Vertex Shaders and Pixel/Fragment Shaders which give developers a lot move power and control over the end result. Figure out what it all means. Learn why the programmable shaders have had such an impact, and become familiar with the different shader model versions.
5. Learn your graphics hardware. Yes, the CPU is a key part of the machine when you're playing games, but arguably the most important these days is your graphics card (GPU). If you're keen on staying in touch with gaming and playing the lateste and greatest, you're going to need know the capabilities of the cards. You should be able to understand what the specifications of the cards mean, and whether or not it's going to suit your needs for a given title.
6. Familiarise yourself with the major graphics APIs. In short, OpenGL and Direct3D! Read, learn, use. You'll need to know about these when you're building your computers and making sure that your cards are compatible.
7. Get a fairly beefy machine. How can you be a true Game Geek without having a large ePenis? Pimp your machine, get some kick-ass hardware, and tell everyone about it while you're mowing them down with your MG42. A PC is by far the best option for playing FPS games, and anyone who says otherwise is an idiot. FPS games are fun on consoles, but the level of control you get with a keyboard/mouse combination by far surpasses that which you get with a controller. RTS can also be a pain on console, so I think PC really is the best option for this kind of game too.
8. Get yourself a console or two. Some games really lend themselves to playing on consoles. RPG, Adventure, and Sports are general categories where the console shines over the PC. Some examples of games which are much better on consoles are PES, Mortal Kombat, Prince of Persia: Sands of Time, and Geometry Wars!
9. Get yourself a hand-held. There many options these days ranging from the old school Game Boys through to the NDS and PSP. Mobile gaming at its best!
10. Read gaming sites. Some of my personal favs are GameSpy, GamesIndustry.biz, IGN, GT.tv. This will give you good coverage of what's going on, what's coming out, what's hot and what's not.
11. Read some games mags. Yes, sometimes a great deal of content that you get on the web for nothing is regurgitated in mags. The good gaming mags don't do that. Get yourself a subscription to something like AtomicMPC, PC Powerplay, Edge, or games™. You won't be disappointed.
12. Get the low down on the devs/publishers. Learn about the major players such as EA, Valve, Ubisoft, Sierra, Midway, Epic, etc. Learn where they fit into the big picture. Why? Because you may find that the attitude and methods of a particular company may just have an effect on which games you buy
13. Support some indies! There are a lot of smaller game houses out there making some really funky games, but they don't get the coverage that they should because the market is swamped by titles made by the bigwigs.
14. Play games. This may seem obvious, but you'd be surprised how many apparent Game Geeks don't actually play that many games. Play online, offline, single-player, multiplayer, console, hand-held, mobile phone, PC, and board games!
15. Don't pirate! Gaming piracy is a huge issue. If you love games you should support the people who make them. When you consider the cost of a game these days against the level of entertainment they give you, they're actually quite cheap. Keep the industry going, and pay for the games you play. This is more of an issue for the smaller players who invest more in original IP than the likes of EA, because their budgets are smaller and their pockets aren't anywhere near as full.
16. Don't cheat! Cheaters suck. They're losers. Just... just don't do it!

There are more things you can do, but this small list should get you underway. If being a Game Geek isn't quite your thing, then perhaps you're more interested in being a Hardware Geek? If so, stay tuned - The Hardware Geek is next up in the series!

For the record, I consider a "Web Geek" to be a geek with a heavy focus on all things Web/Internet. They have a strong understanding of most (if not all) areas of web and web use, good knowledge of Internet software applications and their functions, and have experience with things such as web servers, different operating systems, and web programming languages. You should be able to diagnose, debug and fix issues with internet connections, and be able to configure a router/modem. You should also have an idea of the different types of Internet connections that you can get at home. Coverage of web languages, and other technologies that support them is also key.

So to become the beast that is the Web Geek, all you need to do is...

1. Know the real answer to the question "How do I get on the Internet?". Lots of Internet newcomers lack understanding of the Internet, and they ask questions such as this. As a Web Geek, you should know the proper answer. Most people would think the answer is "Open a web browser". Until then you're not "on" the Internet. This is totally wrong. Any computer that has a network connection which is in some way connected to the Internet physically. The Internet is more than just the Web! As you're about to find out :). So the real answer is: Sign up with an ISP, and get your computer physically connected. If you're computer has a network connection to the Internet, you're "on" the Internet. What you do from here is up to you, and browsing the web is but one of the options.
2. Set up a router and modem. Get familiar with what a router is, and what a modem is, and understand what's different and why they're important. Fiddle around with them and see how they work. Set them up to work with your network and Internet connection. Learn about the protocols that lie underneath (PPP, PPPoA, PPPoE, etc) which allow your Internet connection to work.
3. Protocols, protocols, protocols! You don't have to know them all, and you don't have to be able to regurgitate their specifications off the top of your head, but knowing what they are and what they're used for is important. Some examples are:
   • UDP, TCP, TELNET, SSH, TFTP, FTP, SFTP, SSL, SMTP, POP3, IMAP, TLS, ICMP, SNMP, NTP, NNTP, SIP, ECHO, DNS, DHCP, RIP ... plus many more!
4. Know your applications. So you need to read email? Browse the web? Copy some files? Download some stuff? Find a game server? You should be familiar with at least one of each type of application that can perform each of these tasks. Get familiar with the options, some are operating system specific, others aren't. This is a massive area to cover, and the only thing that will help here is to play. A lot.
5. Get on IM. Being on and understanding the various Internet Messaging applications/protocols is very key (AIM, Jabber (EMPP), MSN, etc), particularly if you plan on being in touch with many other Web Geeks. There are lots of clients that will connect to the various networks, so have a play with a few and pick the one that matches your needs the most.
6. Learn your web languages. Before you jump the gun, I'm not talking about Leetspeak or the apparent "LOL" phenomenon (lolcats, lolcode, lolgeeks, lolpresident, etc - note that I refuse to link to them). I'm talking about web programming and markup languages. Get to know them, they are you friend:
   • CSS, HTML, XML, XHTML, PHP, Ruby, C#, Java, JavaScript, Python, Perl ... and lots, lots more.
7. Know that browsers aren't the same. All of the major browsers Firefox, IE, Safari, etc) behave differently. When you make websites, or browse websites, you'll get to know how different they actually are. So, if the site you're reading looks funny, give another browser a spin. If you're writing your own site, make sure you test your site in as many browsers as possible.
8. Play with the servers. It'd be a good idea to get familiar with the well-known (Apache, IIS, etc) and the not-so-well-known (Litespeed, LightTPD, etc) web servers. Learn about their pros and cons. Get familiar with their characteristics - particularly those that focus on extensibility, security, speed, resource usage and portability.
9. Learn what a webserver machine really is. A webserver isn't a machine that just dishes out web content. It has a stack of software installed on it including (but not limited to) web content servers, database servers, mail servers, DNS servers, spam filters, caching mechanisms, load balancers, etc. Get intimate with the meaning of each of these applications, make sure you know why they exist, what they're for, and which ones you should be using!
10. Use the command line. If you're doing any administration of a web server then you're probably going to have to get used to dealing with the command line (especially if the system is remote). Get familiar with your web server operating system, and learn about how to manipulate your applications. It's a long, hard road but well worth the effort.
11. Put special time aside to get familiar with web security. Read some interesting stories on cyber crime, learn how the pros managed to pull off the jobs they did, find out what the flaws of the systems were, learn why systems are vulnerable. The idea is to get familiar with the massively broad range of methods that attackers can use to break into or bring down your computer. The best way to make your system secure is to understand how the "bad" guys work While you're there, read up on how the good guys have faught back! Get yourself some knowledge that crosses the history of information security. You might think it's not important, but it is!
12. Read a lot of web stuff. You should be an avid subscriber to RSS feeds. Focus on web design, web standards, web development, accessibility, web technologies, languages, and security.
13. Know how to search properly. Searching is more than just pumping a few words into a search engine. Get to know a few different engines, and find the ones that are specific to the kind of content that you're interested in. Practice with different search terms. For a hint, check out my earlier post on searching.

Again, this is only covering the basics of what it would take to become (what I consider) a Web Geek. The big-wigs in the web world know all this and more, so if this is what you're aiming for, best get going, there's a lot to do

Next up, I'll be covering the Game Geek!

Before I even went to university to get qualifications to become an official "paid" geek, I put a great deal of time and effort into tuning my skills in other areas that would help me excel at my job. Below is a list of things that I did which I believe really helped me achieve my goal, and I would recommend doing the same if you're looking to become a paid geek yourself!

1. Learn to touch-type. When I say touch-type, what I mean is "typing without having to look at the keyboard for any reason". Fast typing while looking at the keyboard doesn't count Get yourself a typing tutor and invest half an hour per day for a few months. Before you know it, you'll be setting the keyboard on fire. (Hint: if you can't stop looking at the keys, put a tea-towel over your hands and keyboard!)
2. Learn an operating system (or two). It doesn't matter which one it is, but it's probably a good idea to go for the one that you plan to work with. I'm sure we've all had our fair share of meetings with people who consider themselves to be computer literate, and yet they struggle with basic file management tasks. Using a computer during the day does not make you computer literate. Do yourself a favour, get down and dirty with your OS, and learn how to:
   • ... install the OS from scratch.
   • ... manage files.
   • ... manage disks.
   • ... install/uninstall applications.
   • ... upgrade and patch your OS.
   • ... add/remove users.
   • ... write files to DVD/CD.
   • ... rip albums to a music player.
   • ... move around applications in general (ie. get used to common menu items, and where to find them)
   • ... etc

   Getting this kind of knowledge puts you ahead of a surprising amount of people! It's also a good idea to get an idea of the different operating systems that are avialable, as you'll never know when you might be thrown in front of one of them!

3. Learn your hardware. By this I don't mean that you need to be able to recite tech specs as they would appear on Tom's Hardware. What I mean is learn what your computer is made of (motherboard, RAM, CPU, etc). Determine the function of each of the bits, and the affect that they all have on your system. Understand what it means to upgrade something (eg. add more RAM) and how that will affect your computing experience.
4. Set up a home network. This will give you the grounding that you'll need to understand the basics of networking (networking protocols, IP addresses, DHCP, etc). This is particularly handy for anyone who is going to build web applications, or spend a lot of time in a networked environment.
5. Learn about the web. Find out what that 'http' thing means, and figure out the difference between that and 'https'. Get a basic idea of what happens when you click on a link in your browser. Understand the stages that the whole process goes through from the point you've pressed the mouse button to the point where you've got a fully loaded page on screen.
6. Get familiar with a programming language. This is obviously geared towards the potential coders out there. If you're going to learn to write software, then you're better off playing with one or two languages before you start any formal work or training.
7. Speak to some geeks. Jump on some online forums. Read some blogs. Communicate with the geek community. Learn from their mistakes!
8. Make your own mistakes. This is by far the best way to learn. If things just work first-time/every-time you'll miss out. There's no better way to learn how something works than fixing it when it's broken!
9. Stay in touch. Make sure you keep up to speed with tech, by reading news and RSS feeds (such as Engadget and Slashdot).
10. Give something back Write a blog yourself. Write a tutorial. Help people on forums on topics that you've struggled with. This will force you to make sure you know what it is you're talking about It's also very rewarding.

Do you guys have any other suggestions?