Monday, March 31, 2008

HTML wall of shame, volume 2

Ok, I'd love to comment on this post. I clicked on "Comments" and guess what? Take a look for yourself. Look where it says "Enter the code shown (prevents robots)" and tell me what you see:

If you said "What fucking code?" you are correct. If you said "Some html is allowed" you are partially correct (Reason: What HTML code? Do I get to guess? What happens if I guess wrong?). If you said "Gee, the textbox is pretty big" you are incorrect and need help.

I guess now the world will never know what my comment would have been.

It's called HTML and it's not hard

In 1998, when I was a junior in high school, my friend Dan made a website. It was on geocities or something like that. He showed it to me and I thought it was the coolest thing ever, with links to his favorite sites and some text about him and stuff like that. Wow. So I asked him to teach me how he did that and so he fired up notepad and we started typing out HTML. It took me quite some time to understand tables, but eventually I had my own geocities page and it was awesome. I have been writing HTML in text editors ever since. My point is that it's not hard to write HTML that can be rendered by a browser.

It's even possible to write HTML that is rendered correctly by multiple browsers. I have Firefox and IE on my machine and I test in each of them. Even though IE is the only one that I'm required to support, I still test in Firefox to make sure that it at least looks similar and functions similarly to the way it does in IE. You know what it takes to test your html in both IE and Firefox? Five minutes. Here's how:

  1. Open IE
  2. Navigate to your website
  3. Look at it
  4. Open Firefox
  5. Navigate to your website (optional: 5a. Copy and paste the URL from IE to save time)
  6. Look at it
If in step 3 and step 6 you find that something is significantly different, you might have a problem. With that said, let's move on to:

My HTML Wall of Shame

So here's a blog that's written by someone that I won't identify but his initials are Jeremy Miller. Let's now run steps 1-3

Now, let's do the same steps in Firefox (that's 4-6 in case you've forgotten, and yes I ran step 5a and saved at least three seconds).

And now, our comparison. Do these look the same, similar, or different?

It turns out that they are similar, but not the same, in that for reasons unknown (but they're crappy HTML) the firefox version obscures part of the post, mostly the part in which the punchline of the cartoon is visible, which is more than a little annoying. And because of the nice fluid interface, no amount of expanding the browser window fixes this.

So who to blame?

Well, I don't blame Jeremy for this, it's most likely an issue with and it sounds like they need to "code better" when they're writing their web interface for blogging. But there are a few other blogs out there that have been guilty of this in the past (and two of them are on codebetter, coincidence? Must be. . .) and been impossible to read at various times (I would have liked to have provided a direct link to the offending posts but I don't feel like searching through past posts to find them. I just copied from my IE history because that's the only time I'd open these blogs in IE).

And this isn't limited to bloggers

No, I can only wish that it was only a few bloggers that have this issue. Unfortunately, a good chunk of the internet suffers from it. I've seen websites that cut off the sides, top, and even bottom (that's hard to do) of the page due to crappy HTML formatting in order to try to make the site look all "Web 2.0" or whatever. In order to try to help fix the problem, here are some guidelines:

  1. Test your site using the steps I outline above
  2. If it doesn't work, fix it.

If you follow these simple steps, you can't possibly fail (at least not in this way). Remember, if a high school junior could make a good web page in 1998, so can you. It's not that hard

Monday, March 24, 2008

Visual Studio is not a build tool

Visual Studio (henceforth Visual Fucking Studio) is not a build tool. I have spent the last few days hating Visual Fucking Studio more than ever before. I have hated on it in the past for things like the "Add new item" dialog box that has about 100 different options in no particular order that are all just names for a text file. I have hated the "add reference" dialog box that takes forever to load because it always has to parse every .Net assembly in the GAC and every COM object ever created before it can load (I know they fixed this in .Net 2008 but it still takes a long time to load the first time and I wish it would default to the "project references" tab because that's what I always fucking use). Both of these things that I hate specifically, however, are nothing compared to the build issues that I've had in the last few days.

How we build normally

So on my TeamCity server, I build the project using a Nant script. This is really not hard and it works well. You can also run the build script locally, and thanks to a few ideas that I've borrowed from some people it all works quite nicely and has very few issues. In fact, the biggest problem that happens is when someone adds or removes a file in the Visual Studio project and forgets to modify Subversion to include/remove the file and breaks the build but this is easy enough to detect and fix.

However, people on the dev team absolutely have to have the capability to build the project using ctrl-shift-b and run it with f5 so that they can debug in the Visual Studio environment. This means that when I hit f5 it has to work. This is the way of pain.

Why oh why did I remove that project????

So our application needs to work with both Sql and Oracle with identical functionality. This is one of the most important requirements. As a result, we had to write a data access layer that was abstracted enough so that our factories didn't need to know what platform they were connecting to (there is a reason that we did this ourselves instead of using NHibernate or something similar but more about that in a future post). This project and it's associated dependencies is commonly referred to as the "Data Access Layer" for this project.

Now it turns out that we actually have three or four separate projects (and a few future projects) that will need the Data Access Layer in order for them to live. Initially, we wrote the Data Access Layer in our main solution file for the application, but as soon as we realized that we'd need it in other places, I decided to factor the Data Access Layer out of that solution and give it its own independent solution and build process (it took me about five minutes to modify team city and our NAnt script to set up this new project). So, I now have a separate Data Access Layer solution that I can reference in all projects that are dependent on it. Now I try to build the main application solution and that's when the fun started.

You can't reference that

So you can't reference a project in another solution using Visual Studio. Ok, not a problem, let's just use a file reference. Well, where do we point the reference to? Oh, well there's the obj/debug directory that has the DataAccess.dll and it's associated referenced dll's, let's point it to that. But wait, what about obj/Release? What if we change the build mode? Well, it's unlikely that the developer builds will not be in debug mode, unless there's a bug that is only reproducible in release mode or one of 1000000000 other scenarios that would necessitate it. That means that you'd have to change the reference. What if we move that project around more? You'd have to change the reference. What if we blah, blah, blah you get the idea.

So, I get a great idea: I'm going to create an Artifacts directory in a common location for the build. Then I can just reference whatever DLL is in there so it will work in whatever mode I built the Data Access Layer in. I'll create a postbuild step that deploys them into the artifacts directory and then keep them out of version control. That way, all you have to do is make sure you build Data Access Layer and everything else will build. Cool.

Batch files have been around for years and they're not hard

So I write a simple Copy command in the post build step in Visual Fucking Studio. I run it. "Error: The command exited with code 1." WHAT THE FUCK DOES THAT MEAN? I check the output that Visual Fucking Studio tells me its running and it turns out that some of its macros don't actually mean what you think they mean and append an extra slash on them, so ${projdir)\bin actually resolves to c:\some project\directory\\bin instead. I fix this, it runs. I run it again a few minutes later "Error: The command exited with code 9663." WTF, bitch? What do you want now? I finally start adding echo and dir commands and determine that the command is being run on the wrong directory so no files were originally copied. Now I run it a second time and I get "Error: The command exited with code 9347" or something. This is about when I wished I hadn't quit smoking. I forget what fixed this, but suddenly I'm getting "0 files copied" which is not what I want, particularly when there should be 3 files copied because the source directory has three files in it and copy *.* means copy all files, in this case THREE OF THEM.

Are you sure (y/n)?

It takes me a minute to figure out that the copy command wants to ask you if the files should be overwritten first and if you don't answer it assumes that you don't. Adding /Y to it only surpresses that message but it still assumes that you don't want to overwrite. Fuck you, DOS. I wish I had cygwin installed about now, but that isn't helping me fix the build. So I add a delete command to my artifacts directory prior to the copy and after another "exited with code 1" I determine that there's another one of those directory path issues and finally get it to work. Happiness.

We sure are lucky the build worked at all

So now I start looking at getting the remaining application solution to build. When I first start, it utterly fails for some reason. It turns out that no dependencies were set between projects and there was no build order, so the whole time we were working on this project it was coincidence that it was building correctly. I set some dependencies and changed the build order and put in a reference to my Artifacts directory and the build worked. So I hit f5 to run the application and what happens? App no work. Sadness. After a few more minutes, it turns out that since this is a web app and the UI is in its own project, all the DLL's need to be copied in the UI/bin directory and of course they're not. Our project is structured so that each project should only reference a project that is directly below it. This keeps UI from referencing Data Access Layer which is a good thing. However, without a reference, it won't copy the dll's over because Visual Fucking Studio is not smart enough to follow references in dependent projects. Not a problem, I'll add a postbuild event to copy all the dll's from artifacts and the other output directories into the UI/bin folder. Go back and re-read the previous paragraph because that's pretty much the same thing I went through to add this post build step. I even copied and pasted the commands from the Data Access Layer but it still didn't work. I don't even remember why. I think in total that I spent almost four hours trying to copy like six files into a few directories as part of a build that we're never even going to use except to set breakpoints in the app and run it. I really hate Visual Fucking Studio right now.

Things to fix:

Here's what I'd like to see changed in Visual Fucking Studio:

  1. If I reference a project and that project has references to anything not in the GAC, chase down those references and copy every binary I need into the /bin folder where the app is going to run.
  2. It appears that Visual Fucking Studio just puts all the commands that I add to prebuild and postbuild events into a .bat file and runs them. I would like to see that .bat file. Better yet, I would like that .bat file not to exist and for it to just run the commands.
  3. I want to see WHICH command failed in my steps, not just some useless error code.
  4. I would like to be able to add a reference to another project in a different solution.

I don't foresee myself not using Nant any time in the future.

Tuesday, March 11, 2008

How to give a presentation to people who can read

I've had to give many presentations. I have yet to give one at a major development conference, but I've had to give them as part of my job, as part of school, as part of a sales pitch to venture capitalists, and as briefings to the military. I've probably done dozens of presentations in my day. I've probably had to sit through hundreds of them. Here is my take on how to present.

I can read, thank you

No really, I can read. I don't need you to read me your powerpoint slides. Doing that is a waste of your time, which during the course of a presentation that I may have paid to see, is really my time. Don't waste my time. Your powerpoint slides should enhance your presentation and should help highlight the key points that you are talking about right now. They should not be your whole presentation. In fact, you should be able to give your presentation without any slides at all. Ideally, you shouldn't need anything except an audience, although with most development presentations you need a computer to do some sort of example or demo. Still, you should be able to do at least something substantive without any bells and whistles.

There are no stupid questions. Except for the ones that are stupid

People ask questions. It happens. No one knows everything (except me between the ages of 13 and 19, but now that I'm older there are once again things that I don't know). Therefore, while you are presenting, people will ask you questions. Sometimes they will be relevant, sometimes they won't be. Here's the truth: questions waste your time. No really, they do. There's nothing wrong with questions, but every time you have to stop to answer one, your momentum slows a little and you run out of time a little. You must learn to handle questions so that they can get an answer and you can move on. If a question can be answered in less than one paragraph, just answer it. If you're about to answer the question in the next few slides, tell them that the answer is coming up. If you can't do either of those things, either hold the question until the end or ask them to talk about it after the presentation. I'm sure that your question is very important to you, but if it isn't something that can be answered quickly or on a future slide, the rest of the audience probably doesn't care. When in doubt, ask the audience if they care before you answer that question. Even if it's from me.

Can you repeat the question (hint: you can)

This one is simple: if someone asks a question and you have a microphone and they don't, repeat their question in the microphone so that we can all hear it. If you don't have a microphone, speak loudly.

I don't remember your demo

JP posted about presentations the other day on his blog so here's my take on doing a demonstration on the fly, particularly where you write code: I don't remember what you did. I will probably forget it within about five minutes of the end of your presentation. That's not a problem because you will publish your code somewhere where I can download it along with your slides, right? Wrong. That's a huge problem. The reason is that just because I can see your finished source code doesn't mean that I can see HOW and WHY you wrote that source code. Please, please, PLEASE either record your coding session or post versions of your code as your demo evolves or something. Even putting a few comments in your code would be helpful. You don't have to do this during the demo even, but please give me SOMETHING to work with for your presentation materials. Ideally, you'd be able to provide some sort of video of your presentation but this isn't always possible, so do the best that you can.

It works on my box. . .

Famous last words. So you have your presentation and demo and sample code and everything all working. Then you show up to give your presentation. You get there ten minutes early. Then, the unthinkable happens: You can't get your laptop to work with the projector. Or your laptop crashes. Or you can't connect to your subversion server at your office. Whatever. Don't waste my time with this crap. I'm there to see you, not your props. If your microphone doesn't work, speak loudly. If your laptop doesn't work, runs out of batteries, or won't connect to the projector, then either borrow someone else's (I'll always loan out mine if I'm there) or find a substitute like a whiteboard or a big piece of paper or whatever. If you don't typically have such things, bring them with you. I'd rather you ducttape a 12-foot piece of paper to the ceiling and write on that than waste half your presentation getting your laptop to work.

If you follow some of this simple advice, you will find that your presentations will be much better for everyone. Your ratings will improve. People will find you more attractive. And most importantly, I won't go up to you and talk shit after your presentation.

Monday, March 10, 2008

Party with Palermo

Party with Palermo

Best. Party. Ever.

Certain people have also promised not to do any prairie fires this year.

Wednesday, March 5, 2008

To those who want to hack it together just to make the demo work - please slap yourself

I'd like to talk a bit about the sprint demo today. Jimmy Bogard has an interesting post about letting the customer drive the demo. I think this a great idea, particularly later in the project cycle. I'd like to respond to this post a bit as well as bring up a few ideas of my own about the demo. First, a brief overview of the demo and its place in Agile.

On all other projects we demo only a few times, but on this project we demo every sprint

So part of Agile is that working software is the best metric for progress. We also favor customer interaction and communication. I view the demo as the ultimate way to realize these things. First, it allows you to show your working software so that people can see what has been done. This is much better than progress reports, lines of code, cyclomatic complexity, and TPS reports (make sure you use the new cover sheet). You're also showing your software to the customer, so you're interacting with them and communicating what you've done. In turn, the customer can tell you how well you're doing in meeting their needs. This way, you can ensure that the project is always on the right track and change what you're doing if the customer changes their mind or (more common) realizes that what they asked for wasn't what they actually needed.

The demo isn't that important though

So the demo is a great way to show your progress and get rapid feedback on it. However, the demo is not an excuse for cutting corners just to be able to show off features. Let's say that you're working on a story and it's about half finished. Let's say the half that's finished is the data access portion of the story and that the UI is not yet complete. You don't care about that though, you want to demo this new feature, so you spend like 20 minutes and create an awful hack that implements a crappy use interface. That way, you have something to show.

That sucks

You've now accrued technical debt (more on this in another post), because instead of having something good that you can build off of, you're going to have to wipe out everything that you've done and start over. Or you're going to base your development off of a hack. Or you just never fix the hack because you don't have time. This makes your application less maintainable and harder to test (if you're hacking together application code, you're probably not going to write tests for it right?) and this will be a future problem. If you just do this in one little place in the application, that's not so bad. But it's a long, slippery slope and it's a dangerous habit to get into. My point is that the demo is not important enough to sacrifice good development practices in order to have a better demo. If you can only get part of a feature working, just show that part. If you need an extra day, push the demo back. Just think of a problem like this with the demo as another change that you need to respond to.

Letting the customer drive the demo is like letting a 16-year old drive a Ferrari

So Jimmy Bogard's idea is to let the customer drive the demo instead of development. He says that in practice he's getting better feedback, the customer is less bored in the demos, and the customer feels that something is really getting delivered. Read his post because I think he has some excellent points.

I'd like to point out, however, that the customer can find ways to crash the app that you never dreamed of. Especially early on in development. They also tend to ask "why" a lot, like "why doesn't that link work" and "why can't I add a customer to a group yet" and so on. In fact, I've found that early on, customers only see the incomplete parts of the features. You know, the ones that you have stories for that you haven't picked up yet. They don't care that you can save a customer and that it works on a distributed system running Oracle and Sql simultaneously accross a 56k WAN, they just see that there's no option for selecting a group for that customer. They're going to complain. They're going to crash things. They're going to make the demo long and painful.

This is just like letting a 16 year old kid drive a ridiculously powerful car; they're going to break it and it's going to be catastrophic because they don't know how to drive it yet. However, if you start them on a Pinto or something, then they'll gradually improve and be able handle a more powerful car (like a Volkswagen) and so on until they're driving a Ferrari without killing themselves.

So don't let the customer drive the demo. Yet.

While there are some great benefits to letting the customer drive the demo, it's a very dangerous thing early on in a project. They're going to break things. They're going to see the faults instead of the features. The feedback you get will probably just make you wonder if you're supposed to salute Captain Obvious indoors. Later in the project, your customer will definitely have things to say and they'll be more familiar with the application. Once that happens, they'll be able to drive effectively, they'll look past the few little things that still aren't working quite right, and they'll learn how to give good feedback during the demo so you'll get some benefits from letting them drive. Just don't rush out there and try this on your next project's first sprint demo because I believe that you're asking for trouble