To Comment or Not to Comment

Anyone who has had programming classes knows that one of the primary things they push on you is that all good programmers comment their code. They don’t always tell you how much commenting you should do, although some do give good advice. How does one decide how much is enough.

Comments are great because they are basically communications between programmers to help with the logic that is going on in the code. Sometimes the two programmers are the same person. I think a good rule of thumb is to comment just below your own skill level. This means to comment just enough to help someone of almost the same skill as yourself along. You don’t want to comment your code to the point that it clutters up the rest of the source, but you want to be able to read through your own code and quickly find the cause of any potential bugs. You never know when you’ll have to go back through your own code. Chances are you won’t remember what exactly is going on at any particular point, especially if you work on a lot of projects.

Of course, there are always conventions that are mapped out beforehand for most developing teams, but if you are working solo, you should comment as if you are in a team environment.

I personally find comments distracting and ugly when viewing code. I don’t particularly care for method and class header comments. They rarely give any useful information. Inline comments are very valuable, however. So if if the coding standards of your team require class and method headers, put them in, but if you are solo or there’s no coding standards in place that require these types of comments, don’t use them. You should be able to look at any method and tell what kind of parameters it takes, and you should be able to quickly find the return type. These aren’t necessary and break down code readability in the end.

Comment changes. If you have to remove some code, comment it out instead of deleting it. This will help you revert changes or come up with better solutions if it is later found that the new code is buggy itself. If you have some bit of logic that is complicated even to your own eyes, comment it and explain how it works. Other than that, keep comments to a minimum.

Updating Whats-hot-weekly

My task for this morning is to add additional site codes to It’s not an easy task. At least, it isn’t as easy as I thought it would be. All of the categories are pulled from a database that I refresh every so often. The database only contains the categories for the US eBay site. This is where it gets hairy because I wasn’t aware before now that the other countries used didn’t categories. So, now my task is to add all the categories so I can implement the additional sites.

This is going to take a while. The US along takes around half an hour. There are many other sites. I’ve recreated the database adding a field to record the site_id. Next I’ll run my scripts to populate the database with API calls. After I populate the database for the US, I’ll switch the site codes manually and add the next site. I would automate this but I would rather monitor it anyway so I thought I may as well do it manually.

The big issue that will come up later is currencies. I’ll have to adjust for that. I’ll also have to recreate the same code on the static version of the site.

While I wait for the database to refresh, the old site is still running as normal. I have a development environment that is a working copy of the production environment. I’ll make the switch there, then simply move it over to production from there. There should be exactly no downtime to the site. I hope.

Browser nuances

I’ve recently been working on a new site. I prefer to write the xhtml, css, php, and javascript without using any WYSIWYG interface. This is great for a few reasons.

  1. I can practice coding
  2. I can manage my own code better
  3. I can verify that the code is W3C compliant
  4. PHP/MySQL doesn’t preview very well in pre-Dreamweaver CS4 WYSIWYG environments.
  5. Neither does javascript

I personally switch back and forth between three editors. I use Vim as much as I can. I love that old editor. I use Notepad++ mainly for vbscripting and quit web page edits. Finally, I’ve found that I love the code view in Dreamweaver. It’s a great tool. So, now that I’ve gotten that out of the way, let me explain the one thing I can’t stand about web development. I love everything about it except for ……browsers. All web developers will tell you that writing web pages for Internet Explorer, Firefox, Opera, and now Chrome is a headache. It’s not that writing a webpage is a headache. It’s the fact that each of these browsers have their nuances. Here’s an example… I’m working on a fluid layout for this new site. I have a search box that sits in a div in the upper left corner of the browser window.

Here it is in IE7:

Nuance 1 IE7

Notice the border around the search box. It goes above the top of the browser. This is because I’m using a negative margin value to move the search box up. I did this because in Firefox the search box was too low. I was developing the site and previewing in Firefox to check my code. So I adjusted the CSS in relation to what I saw in Firefox. Here’s the same element in Firefox:

Nuance 1 FF

Again notice the top border of the search box. In fact, notice that the whole box show up in FF. Here’s the same example in Google’s Chrome browser:

Nuance 1 GC

You may be saying to yourself, “that looks exactly like the Firefox example. You would be correct but here’s my second example of nuances. Here is my category menu just under that same search box…in Firefox:

Nuance 2 FF

That’s how I wanted it to look. I’m using jQuery to get the rounded edges in the inside div. Check out the same edges in Google’s Chrome:

Nuance 2 GC

When one spends hours trying to make a design look the same across all browsers, it’s frustrating to say the least. I haven’t mastered it yet. I would really rather spend this time adding AJAX to the site so that it will be functioning and ready for deployment.