During my time in the Army, I used to get rankled when I’d see Television or Movies portray soldiers.  Generally, they’d get something wrong; and usually, it wasn’t just something minor.  It didn’t usually bug me when it was clear they weren’t trying to get it right. It bothered the hell out of me when it looked like they tried to get it right, but failed in some way that could have been prevented if they would have spent $1000 and hired a military consultant for a day.

The same thing bothers me about naming in source code.  Well, not the military part, but the ‘bad acting’ part.  Here are a few bad names I’ve seen in source code recently, and they are all from commercial applications.

timeout  – Describes how old a file should be before it’s deleted

narrative – Refers to the ‘help’ field for a form or page.

nounset – where noun can be anything, like ‘bird’ or ‘category’ or ’email’ or ‘password’. The suffix ‘set’ is added to it to denote a ‘set’ of that noun. In some cases, it refers to a ‘template’.

That’s just a few; and there are more out there, probably in the application you work on.

What’s so wrong with bad naming?

Let’s say you have a new developer come onto your team. it doesn’t matter if this developer is just out of college or if he’s a 10 year veteran. He now has to learn what those words mean.  He then has to apply those names to the intent behind them, and daily has to remind himself of what they mean.

timeout  – fileage

narrative – instructions

nounset – nouns, or nounTemplate (This can also rely on the fact that in databases, a table is considered a collection of things; adding ‘set’ is redundant).

 

 

 

 

 

Last week, Jeff Atwood and Joel Spolsky discussed open-sourcing Stack Overflow. This week, Micah Martin (of Coding Context) asked a Stack Overflow question about releasing his site, Wikipedia Maze, as Open Source. 

Both had the fundamental question:

Should I release my code to the open-source community?

Short answer: Just releasing a project as Open Source is a mistake, for the same reason that handing a hungry man a fish is a mistake.

I’ve trolled SourceForge for years, but my interest in the myriad of projects op there is precisely zero. Why? Because handing me code doesn’t tell me why it’s useful to me. It’s like putting me in a library with no card catalogue. 

I’m not saying that you should never release a project as open-source, but that if you’re going to do so, it’s your job to make it worth something to other programmers, because the best code in the world isn’t worth anything if no one knows it’s there.

Going Fishing

Consider this gem from Quake:

float InvSqrt (float x){
    float xhalf = 0.5f*x;
    int i = *(int*)&x;
    i = 0x5f3759df – (i>>1);
    x = *(float*)&i;
    x = x*(1.5f – xhalf*x*x);
    return x;
}

If you were a smart programmer who got things done, you’d probably instantly recognize this for what it is: Awesomeness wrapped in bacon.

For the rest of us, it’s a clever piece of code that’s discussed in detail here:

The magic of the code, even if you can’t follow it, stands out as the i = 0x5f3759df – (i>>1); line. Simplified, Newton-Raphson is an approximation that starts off with a guess and refines it with iteration. Taking advantage of the nature of 32-bit x86 processors, i, an integer, is initially set to the value of the floating point number you want to take the inverse square of, using an integer cast. i is then set to 0x5f3759df, minus itself shifted one bit to the right. The right shift drops the least significant bit of i, essentially halving it.

Using the integer cast of the seeded value, i is reused and the initial guess for Newton is calculated using the magic seed value minus a free divide by 2 courtesy of the CPU.

If you were like most programmers and you scrolled across this function, you’d probably wonder what the heck it did. In fact, unless someone took the time to tell you, you might even skip over it.

 

But, what if you saw the article on Slashdot? Even if you had no idea about it before hand, seeing more than just the code immediately helps you as a programmer.

The end result?

You are now a better programmer because someone took the time to explain the code, instead of just releasing it into the wild.

Teach Me to Fish

If you’re going to release your site as open-source, then go the extra steps and take the users through the problems you had. Make it into an n-part blog post that details the neat parts. Write a book. Record a Podcast. Do something other than just releasing the code.

There are plenty of lessons we could learn from Stack Overflow and WikipediaMaze, but seeing the end result isn’t as useful to other programmers as taking them through your code, and showing them why you made the decisions you did. You get recognition and Google traffic, and the programming community learns how to fish.

By now, you may have heard about Adam Savage’s skirmish with AT&T over a very familiar story: Man gets overcharged for internet access, takes case to internet, and wins.

His Tweet (a message on Twitter) simply read: “AT&T is attempting to charge me 11k for a few hours of web surfing in Canada.”

His message spread amazingly quickly on Twitter. Within three hours, AT&T was the second most discussed topic on Twitter, second only to Michael Jackson.

By the end of the day, the carrier was “very gracious about taking care of it all,” Savage said, deciding to free him of those costs.

So holds the power of the internet.  This sort of thing has happened before and it will happen again. It’s even happened to me.

The funny thing is, the age old adage “There’s no such thing as bad press” isn’t true anymore, and companies like AT&T and Verizon know just how easy it is to lose customers. Why do you think they require service contracts?

I’ve been known to jump from one service provider to the other if they start treating me badly, and with this newest text messaging problem, I probably won’t jump back to AT&T any time soon. I’ll just wait for the iPhone to become a non-exclusive item.

The complainers, the people the people that bad mouth your service, now have a voice. A very loud, very obnoxious, and very addictive voice. You used to be able to dismiss them out of hand; but now one bad service call with one customer can provide years of online enjoyment.

So, what do you do?

You can’t make everyone happy; that’s obvious. But you can take those singular “We messed up” moments, and turn them into something good. In Soccer, we call those pivotal moments in games the Moment of Truth. It is the occasion when the referee has to make a decision that will forever shape players’ perception of him throughout the match (and possibly his career). It happens in almost every match, and getting that singular moment right can do a lot to repair or extend credibility where you might otherwise have little.

In software, that means openess. Not the Government 2.0 kind that really isn’t, but the kind where you address complaints and complainers head on. You can no longer pretend that they don’t exist. Steve Krug wrote in Don’t Make Me Think  about how company FAQ pages never really tell you anything you really want to know, and he’s right: they ought to.  Businesses now must hire  ‘Social Media’ experts or ‘Community Managers’ to address customer service issues in this new age of the internet. As Jeff Atwood writes:

To have a personal brand, you must do something remarkable:

 

• lead a user group
• create a popular open-source project
• write a blog
• publish a book
• publish articles
• speak at conferences

Do whatever you like. Pick one, pick them all, or pick something that’s not on this list.* As long as it’s public, and it advances your skills, you’re creating a personal brand. And that will help your career far more than technical chops ever will.

His advice is as salient for businesses as it is for individuals (and software companies doubly so!). What can businesses do to build their online brand?

• participate in social media (not just press releases, please)
• encourage your employees to participate in social media
• only censor the business proprietary stuff
• let the warts shine through
• become personable

Having a ‘blessed’ social media account is not the same thing as 5,000 employees having blogs and twitter accounts. 1 voice is meaningless, but a sea of employees generally talking about their day/life/work makes me interested about those things. I never gave Dell a second thought until I saw that they have a lot of employees with Twitter accounts. Now their brand is more personal to me.  Microsoft was an early adopter of this with encouraging blogs being written by their employees. The question is, why isn’t your company building its online brand through employee crowd-sourcing?

If you don’t build your company’s online brand and keep it polished, someone will tarnish it, and you’ll only have yourself to blame.

In our last wonderful adventure, I lamented the state of website registration, and took umbridge with SQL Server Central’s approach of requiring a user to log in before viewing the article.

Since then, there have been two developments:

SQL Server Central‘s registration requirement can be beat by Firebug

The CEO of Red Gate Software personally* told me that they’d get rid of the registration requirements for that website.

All it took was Joel Spolsky mentioning it on his Google talk about Stack Overflow. 

As an aside, while I’m very pleased with Red Gate’s move, I can’t believe it took a celebrity calling them out for them to change their tune.  If they had taken an afternoon and conducted a usability test, I find it hard to believe they wouldn’t have found out that this is an issue for users.

Of course, this brings out another problem.  I’m using the blogs of two well-known programmers to add credence to what I believe as a programmer. Why shouldn’t I? They’re smart guys, and they get things done.  The problem it causes is that for all the progress we’ve had in Software Engineering, the ‘best-practices’ are still a collection of blog posts inter-mingled with light reading.

 

Unlike other disciplines, there is no Software Engineering bible that contains the canonical Dos and Don’ts. There can never be.  Once a book is published, it could be obsolete.  We move too quickly for any one book on Software engineering to have a long half-life.

Our ‘Bible’ is and probably always will be a collection of blog posts that reference books that are either already irrelevant, or soon will be.

 

As an example, Steve Krug’s book, “Don’t make me think” covers web 1.0 very well, but doesn’t cover web 2.0 at all.  How should web designers handle Ajax? What is obtrusive, what are the best practices?  We only have blogs to tell us, and perhaps that’s the way it should be.

There’s been a lot of talk about crafting a “Technology Bill of Rights” lately, and all of it centers around bestowing users of software and hardware with ‘rights’ related to that technology (pardon the redundancy).  There’s a giant sized problem with this idea: All of these ‘rights’ infringe upon the people that are selling this technology.

To understand why this is a bad idea, we first must understand the term ‘Bill of Rights’ and its origin.

Background

The Bill of Rights is the common name given to the first ten Amendments to the Constitution of the United States.  These rights were written down in an attempt to garner more votes for ratification.  The argument for them was that without them, the government would have free reign to limit free speech and due process, and property rights.  The argument against them centers around the idea that these rights are not bestowed by any man, so they cannot be taken away by any man. They are properties of Natural Law. I have them because I was created, and in order to fulfill my purpose as a Human being, these are things that must be granted.  Notice that none of the rights that I am granted infringe on anyone else.  My right to Due Process does not harm you; and my right to Free Speech does not limit your right to the same. I have the right to bear arms because it is necessary to protect myself and my property from individual or collective tyranny.

The Problem with The “Technology Bill of Rights”

This “Technology Bill of Rights” does not operate in the same regard.  It ‘grants’ rights that otherwise do not exist according to Natural Law, and in doing so it infringes upon the private property rights of others.

Article 1. Any individual shall be able to choose anonymity when posting to Internet sites – This ‘article’ infringes upon private property owners.  It uses coercion and force (rule of law) to tell someone what they can or cannot do with their property — the very antithesis of liberty.

Article 2. No network provider may constrain or restrict access to the Internet in any way, shape, or form other than agreed-upon access speeds – This ‘article’ (once again) infringes upon private property owners and businesses. It forces them to swallow costs and not cater to the needs of their customers.  Let’s say, for instance, that a particular Internet Service Provider (ISP) wanted to restrict access to all Adult material as its selling point (to become the premier ‘family oriented’ ISP); this article would prevent them from doing that.  To say that I must allow access to morally objectionable material on my access point takes away my property rights.  Outside of that, it is tantamount to interference in the market, which is never good for customers, and most certainly has unintended consequences.

Article 3. No individual shall be held liable for effects of malware or malicious code unknowingly run on a personal computer – This article doesn’t belong in any bill of rights.  There are already laws governing destroying others’ property (which this most certainly qualifies as), and all it takes is common sense to realize that the government’s actions bordered on idiocy (when doesn’t it?).  If anything, this is an instance where two things should have happened: 1) Jury Nullification should have been explained to the jurors and 2) Prosecutorial misconduct and over-reach should always be pursued.

Article 4. A company that produces and sells closed source software for use on computers shall be responsible for the security of that product, and a user has a right to seek damages in the event of a failure to secure their product – This is an attempt to legally offer redress for vulnerabilities found in Software.  For as long as software is made by humans (in the same way that bridges are), there will always be failures.  Knowing about vulnerabilities and not patching them is different than not knowing about vulnerabilities.  This article does not differentiate between the two, and thus doesn’t pass muster.

Article 5. Any software or hardware used to conduct or support laws and public policy shall be open-source – The author of this article takes a good idea and turns it on its head.  A better idea would be to reduce government to the point where this isn’t needed. I agree that citizens ought to have a right to confront source code if it is used to charge them with a crime; but to extend that to all software used by government? No thanks.

Article 6. Any media content legally purchased by an individual shall be available for private use on any device, at any time – This article once again limits a businesses right to limit how its property is being used. Notwithstanding the idiotic business decision behind Digital Rights Management (DRM), it is the right of those producing these products to determine how they are used.  It’s an utterly stupid decision on the part of businesses, but it is a decision that is buoyed by the free market.  When it’s more profitable for companies not to use DRM, then they’ll stop using DRM, or they won’t be able to compete as readily.  Stardock has already dropped DRM, and others are following suit.

Missing the Point

Other so-called ‘Technology bill of Rights’ don’t fare so well either from a ‘free society’ perspective.  More to the point, they operate within a faulty framework: That Congress is allowed to craft laws outside of its Constitutional limits — which is exactly why people are clamoring for these changes.  There’s a simple answer to all of this: get government out of these issues. de-regulate and stop the utility protectionism that surrounds the cable and phone companies. Elect Congressional leaders not based on what they can do for your particular class; but rather how compatible their ideas are with a constitutional republic.

The bottom line is that while this ‘Bill of Rights’ may seem like a good idea; it has a whole host of issues that are incompatible with a free society. You cannot make one group more free at the expense of another group. That’s not freedom; that’s tyranny of the majority. We call that democracy.

What do you do when a business people ask you for a webcam on the moon*?

You find out how to give them a webcam on the moon.

You Do Not say:

“It’s not Possible.”

“I can’t.”

“No.”

“Can’t be done.”

Or any derivative of the above.

We are in a recession, and we’re entering a depression. If you follow the Austrian School of Economics (read: The school that predicted exactly how this recession/depression came to be, and when it would happen) then this is an incontrovertible fact.

You do not say ‘no’ when your company’s future, or more importantly your job, is on the line.

I realize that it’s not feasible to put a webcam on the moon. I get it. Business people are just as smart as we are, and they know that it’s not really possible to put a webcam on the moon.

That doesn’t stop you from finding out if that’s what they really need, and if it is a webcam on the moon, then do your damnedest to give it to them.

I am not advocating being a ‘Yes Man‘.

Yes Men do not have opinions, they don’t have concerns, and they don’t give better ways of putting that web-cam on the moon.

You do.

How do I get a web-Cam on the Moon?

Well, you don’t. Even if you’re very well funded, and you have your ducks in a row, chances are: you will fail. Does that mean you don’t try? No. If you’re a software developer, it’s not your decision whether or not the project goes forward.  It will go forward (and with sometimes disasterous results). Your purpose centers around whether you’ll bring up your concerns and possible solutions when the project falters.

Always have a solution, even if that solution is to ‘do nothing’.

*Credit for the ‘Web-cam on the moon’ goes to ShawnY at FlexAdmiral.

In software engineering, an anti-pattern (or antipattern) is a design pattern that appears obvious but is ineffective or far from optimal in practice. (Source: Wikipedia)

 

Whether the users are Software Developers or a sixty-two year old journalist I affectionately call ‘Dad’, users agree that Website Registration blows.  It’s a hurdle we must endure to get to our beloved internet content; or at least that’s been the status quo for a number of years.

Background

In a recent twitter conversation with @SQLServerCentrl, I complained to them about their registration requirements.  I hadregistered to see a certain article (it turned out not to help me, even though the search terms indicated it would); and I kept receiving their newsletter. As I was clicked on a link in one of their newsletters a few weeks later, I realized that I had forgotten what password combination I had used to register.  Then I realized that you can’t see any content on their site without registering.

I asked them about it, and their response was:

 

@gortok sorry to hear that, but the registration allows us to track stats. If you’re getting the newsletter, you should be registered

That doesn’t make any sense; doesn’t Google Analytics provide anonymous tracking?

That tête-à-tête ended with them pulling out the numbers card in Argumentum ad Populum style.

How many times have you, as a software developer, heard this refrain from your business analyst or marketing department: We need to be able to track users and collect information about them so we know who to market to. This refrain normally spawns a requirement (or two) that the end user must register in order to see content on the site.  All of the tie-wearers agree that that’s the only way to get all of this information, and so it is done.  If you develop software, and you let this happen, you have now commited the worst kind of design pattern, the Usability anti-pattern.  Jeff Atwood calls it a ‘barrier’, but it is so prevalent in websites that it can only be considered a design-pattern at this point, and an anti-pattern at that.

It’s an anti-pattern because while it’s easy to do, and it fulfills the business requirements, it gives users a bad taste in their mouths about your website.  When’s the last time Wal-mart required anything out of you other than walking into their store? 

There are reasons to ask a user to register on your website:

Common Reasons to ask for Website Registration

 

1. It’s the easiest way to track what you look at.

2. It’s our way of tailoring what we deliver to you.

3. We sell your information, we can’t sell it if you don’t give it.

4. We have ‘affiliates’ that we ‘share’ your information with to ‘better serve you’.

5. No reason given. Just a Privacy Policy written by a Lawyer (That gives me a warm-fuzzy).

 

If you look at all of these reasons (except #3); you’ll notice one thing they all have in common. They’re bogus. They don’t mean anything.  They’re simply excuses to get you to give them the benefit of the doubt.  When you go into a store to look at a product; does the store owner stop you at the door and force you to give him your name and address before entering? The answer is a resounding No.

What’s worse is that asking for personally identifiable information from a user now brings up legal issues, as this FAQ regarding registration from the Chicago Tribune website so aptly shows:

 

We specifically ask your birth year to assure compliance with our Privacy Policy concerning minors.

Solution

Wouldn’t a better idea be to not ask for personally identifiable information in the first place?

Besides selling your information or spamming you with emails, there is no reason for a website to retain any personal information about you.

Yet, we seem content to let this happen across our web-applications and websites. We force customers to give us some sort of information in return for viewing our content.  In the worst cases, you must log in every time you want to look at content (SQLServerCentral), and in the lesser cases, you only have to register and log in when you actually want to buy something.  At the good end of the spectrum, you have websites that set the bar low enough where this isn’t even an issue (Stack Overflow, Google, Amazon).

The harder (yet infinitely more usable) pattern is for a website to take one of three paths:

1. No registration whatsoever.  Why would you want to register to read daily content, some of which you may never even care about?  What does registration get you? Nothing.  Registration is used simply to tie you as a user to what you look at.  Guess what? It’s the same information that can be found with Google Analytics. The only difference is, this information can’t be sold to a marketing company.
2. Incremental registration after the user has poked around your site. A great example of this is buying something off of NewEgg or Amazon. You select the product, fill out your billing address, buy it, and then they ask you to fill out one or two more fields (usually just choosing a password), and that’s it.
3. Registration for ‘advanced’ features or for continual participation. Stack Overflow uses this method.  As a Unregistered user, you can ask questions, browse the site, and you can even gain reputation. However, that reputation doesn’t persist across cookie deletion unless you register.

 

All of the methods I mention are widely used, and they’re all relatively easy to do. So why do businesses still ask for this information?

It’s easy, it’s cheap, and by the time you realize you’ve been hoodwinked, they’ve got your information, and you’re left with whatever they’ve seen fit to give you.  In most cases, you’ve gotten the short end of the stick.

 

In our previous adventure, I talked about building an ASP.NET website for a local school.  This site would have a small Content Management System attached to it.  Nothing fancy, just something small.  But you see, I forgot a cardinal rule of programming: Get the functional specification. Oops.  Luckily, the site idea has been swimming around in my head for ages, so it should be rather easy to crank one out, right?  Let's hope so.  This specification will follow the example set by Joel Spolsky of Joel On Software.  Without further ado (or maybe with it, given my rather long intro), the functional specification.

 

Overview

stannscatholicschool.com is a website that allows teachers from St. Anns to update the parents and community on what is going on in their school.

Warning: This specification may cause paralysis if read for too long. It's not complete. It will change. Hopefully not too much. The screens shown here are for illustrative effect, they are not meant to be taken as the final product.  The look and feel of the site will be refined and changed based on user feedback.

This specification only deals with what a user would see when they visited stannscatholicschool.com. 

Scenarios

In designing products, it helps to imagine a few real life stories
of how actual (stereotypical) people would use them. We'll look at two
scenarios.

Scenario 1: Samantha (The Teacher).
Samantha is a Teacher at St. Anns.  In between dealing with kids, parents, meetings, and planning, she has very little time to worry about weather or not people on that distant thing called the internet are kept up to date with what is happening in her classroom.  Up until now, she's always just put the newsletter in the Kid's bookbag, and sent them home.  If the parents needed to read something, the hope was that the child wouldn't ingest it or use it for spitballs.  For anything important, the United States Postal Service was used. Given that we're 8 years into the new millenium, and a full 12 years after the World Wide Web became huge, Samantha (being the smart teacher that she is) knows that it'd be far easier to copy and paste her news letter onto a website than it would be to print it out, make copies, and put them in her kids' bookbags.  Not to mention it'd be much more 'green'.

So Samantha logs on to stannscatholicschool.com, and decides to upload her news letter.  In friendly way, the site asks her what she wants to do, and if she wants to upload the newsletter, she simply copies and pastes it from Word, hits 'save', and her work for the day is done.  She can do this for every other section on her teacher page as well.

Scenario 2: Tammy, the Mother.

Tammy is the mother of two wonderful children that seemingly lose their newsletters walking from the school to their car.  It happens.  When she needs to find out information, she simply navigates to the site, and can easily select her child's classroom.  Once there, she sees that the weekly newsletter has been posted to the site, along with a note about upcoming events that's easily viewable.  Since she'd forgotten about the Picture day, she goes ahead and calls the school and asks if it's too much trouble to be sent another form.  Just like that, she is kept up to date on her children's school events.

 

Where to Go From Here

At this point, we've got a jist of what we want the site to do, so we'll go ahead and base a data schema off of this and start building the site.  We're pretty sure we're not going to get it right the first time, so we're not really worried about that. 

---

This is the site in a nutshell.  In the next article, we'll work on the data schema.

I have been following ASP.NET MVC ever since it was brought up as the meta-pattern behind Stackoverflow.  As I referred to in my last post, I'm in the process of building a website for a local Catholic school.  Part of the the act of building the site is determining whether or not I want to go the extra mile and really make it something special, or if I just want to 'make it work'.  The traditional Web Forms + NHibernate + SQL Server will make it quite easy to build; but then I wouldn't be learning anything new.  MVC does seem like overkill for the task at hand, however.  So the question at hand, Speed? Or doing it the right way?

Over the past few months, I've been working on upgrading St. Ann's Catholic School website from the circa 1996 look to something more modern.

So far, I've done the following:

• Organized the site in a logical fashion
• Implemented a menu system using Tanfa's CSS driven Menus
• Used Purplehaze.css as a baseline for the website's cascading stylesheet
• Created and helped edit static content for the site (I instructed a non-technical person on how to upload the static content and change the content so far.)

 Since that's done, I can focus on the dynamic nature of the site. There are a number of stated features to be implemented, including:

• Ability to add weekly newsletters
• Ability to add homework
• Ability to add events (a la Google Calendar)
• Ability to see recently added information

 To make this happen, I need to take the following steps:

1. Create Database Schema
2. Use NHibernate and My Generation to create POCO objects and theData Access Layer and Mapping files
3. Create Business logic and create individual modules listed above
4. Deploy and Maintain

I intend to use this blog to document this, and obviously the code will be released (open source, license unknown) to allow other schools to create dynamically driven sites without having to rely on sites like TeacherWeb. I don't have anything against TeacherWeb, I just can't believe that schools would pay for what amounts to a WYSIWYG editor (not unlike Frontpage).

You may wonder why I'm using CSS Menus and Stylesheets from other authors instead of rolling my own.  I could do both (though the latter would be far easier than the former); the reason is easy, never design what you can steal.