Documentation....A huge hassel.

I once failed a class because I did not create any documentation to go with the program I had coded. The class was Business Programming - C++. The only assignment for the entire class was to build a database backed program. I choose to do a bookstore inventory program. I wrote the program during the final weekend of classes. When my professor went to grade it, it crashed. I didn't think he would try to enter a string when I was asking for a number. Why would he do that? Because end users would do that, that's why. He gave me an F, not because the program crashed. He expected it to crash. He gave me an F because I didn't provide documentation on how to recover from a crash, or any documentation on how to use the program. I thought it was obvious. NOTHING is obvious to a user, lesson learned.

As I progressed through school, documentation was always a key part of whatever programming, web design, or software development class I was taking. Comments in code? Better be there, or points off your assignment. Wireframes for your webpage....half of the assignments for one of my classes.

At one of the jobs I've had, I asked if there was any documentation for the program I was going to be working on. I was laughed at. For another project the user manual was five years old, which is way out of date, and I was told that there was no point in referring to it at all.  I'm sure that this is not the case at every company, but most of my co-workers seemed to think that this was totally normal.

I think that documentation is a very important part of a project. This is why a significant portion of some classes are spent on how to do documentation correctly. I really wish we had a design document for my current project. Not so that I know what I'm supposed to do doing, I already know that, but so that I can point to it and say, "this is why the program was created this way". Documentation takes time to create though, and time is money. I work in what I feel is a volatile environment, one where changes to program requirements seem to happen on a regular basis. This is not a productive environment to code in, at all. This is usually the result of the customer not knowing exactly what it is they want, or the lack of a design document and a process to go through to get something changed on it. But what’s done is done and there isn't really a good way to go back and fix it. Not without moving backwards, which is something you never want to do. It kills morale, and in the case of doing contract work, makes it seem like you've wasted time and money. So the solution is to keep trucking forward.

So why don't we start doing documentation? Spend a little less time on coding in order to get our documentation to where it should be? Because of the volatile environment. Trying to document something in such an environment is a bit of a time waster. I know because I tried. I wrote on documentation on a process. It took me between a week and a week and a half to get it the way I wanted (wasn't the only I was working through, so less than 40 hours). Within a month, it was out of date and needed to be updated. Now, do I spend another week to change it, just to have it go out of date on me again? The process it was documenting was a relatively minor one, and would only eat up a day of my time to explain or show how to set something up. We have a pretty small team and this process wouldn't have to be gone through many times by the same person. So, it was decided that this particular piece of documentation was more trouble than it was worth.

I'm not saying that documentation isn't important. I think it's extremely important in getting a project off the ground. However, once a project has gained some stream, the usefulness is diminished to the point where the time spent to create new documentation hampers the ability to make progress. The classes I took where we were forced to create wireframes for our web applications or programs before we started working on any actual code were dead on. Not just with how important documentation is, but at what stage it should be done. In the beginning of the project, on the upstream, where changes are easy to make because there isn't much to change. It should be part of the overhead cost of doing a project, not an ongoing cost, because the ongoing cost is so much more expensive.

So...documentation is good, as long as it’s done as soon as possible and isn't subject to change very often. Otherwise, it’s really more trouble than it’s worth, as out-of-date and wrong documentation is often worse than no documentation at all since it can lead people astray and waste their time. And time is money.

Almost a whole year later...

It's been almost a year since I've graduated from UCF and started working at my current job. The academic world and the professional world of programming are similar but different at the same time.  I still know many people who are still in college studying programming (or soon will I hope). They are sometimes baffled by the way things are done where I work as opposed to how things are done in the classroom. This isn't to say that the classroom way is wrong, or that the way its done where I work at is wrong, they are just different. This is mostly because of the priority shift of what is ideal in the classroom setting as opposed to the more realistic or "cheaper" way things are done in the workplace. I'm just going to sum up some of the differences I've noticed thus far here and in the future go into further detail of each. These are my own unique experiences and I'm sure aren't the same everywhere.

1) Documentation....often an assignment itself leading into another assignment in school. A huge hassle no one has time for where I work.

2) Group Projects....in school if one person doesn't pull their weight, it seriously sucks for the whole team. Where I work, as long as you do what you're supposed to be doing...you're golden.

3) Silly mistakes.....they happen and are expected in school. At work....at best they seriously annoy your coworkers.

4) Time management and Organization....all those classes about college success you thought were useless to get through college, pay attention because after college these skills and habits can really save your bacon.

This post and the ones that follow are more about general purpose development and not isolated to writing code. If you're looking for code I'll get back to it one day. This post was really to try to get me back into writing stuff, hence the lack of content here. 

Web Linker

     As far as I know, most web development is done with tools which are little more than text editors. For as long as the web as been around, you'd think that these tools would be a bit more sophisticated. Sure, they have syntax highlighting, code hinting, and automatic spacing. Dreamweaver has a design view that will auto create the appropriate HTML and CSS for you, and Word can save a document as an HTML file. But, I feel that there should be more.

     Content Management Systems like Wordpress and Drupal does wonders for designers who don't have the time (or knowledge) to edit raw HTML and CSS. But at what cost? Have you seen how many stylesheets are on some of those sites. There is a main stylesheet, a stylesheet for the theme, each plug-in has its own stylesheet. It's madness! I've even seen websites that don't come from a CMS with upwards of 7 - 10 stylesheets. And then there are all the javascript files that are called; custom scripts made just for the site, jQuery, some other script from some other place. I saw one website with a total of 14 external CSS and JS files. That is an extra 14 requests the browser has to make, not including having to get any images that aren't cached.

      I read on Stack Overflow somewhere that firefox limits the number of concurrent requests to 6. I'm assuming that other browsers do the same and that the number of requests they limit is probably comparable. Lets say that a good connection has a ping of about 100ms, those extra requests will take a minimum of 300ms to get. 300 milliseconds. Thats pretty quick. But what about those who don't have such a great connection. Maybe something is interfering with their wifi, or they are using a mobile device and the network is clogged to high hell (like using a iPhone in New York City). What if their ping time was around 500ms. With that many external files to load, your looking at a minimal of 1500ms. Thats just getting the stylesheets and javascript files. Any images that aren't cached on the client computer would have to be requested as well. Still kinda quick in people time, but that is FOREVER in computer time. And yes, people do notice when a website loads slowly. I always dreaded the "my computer seems slow" phone call for tech support.

     Why don't we just embed the styles and the javascript directly into the webpage? Then you only have to get one the webpage and any images associated with it. Lets say hello to code maintenance. Those who have had the pleasure of inheriting any sort of code to update or fix, will know what I'm talking about. Code is hard to really hard to read. Much harder than it is to write, and putting all your code in one giant file is like writing a ten page essay without dividing it up into paragraphs. In writing, a paragraph should really have one main idea, with some details sprinkled in to support that idea. In programming, each individual file is a paragraph, one main idea, or purpose, and a lot of details sprinkled in to support that purpose. This makes it easier to read, find bugs, and allows you to know where to look to change something.

     So web developers compromise. They keep all the files separate so that their code is easy to maintain at the expense of efficiency. They justify this by saying that the trade-off is worth it. Of course, they are talking from their perspective. If they can load their page reasonably quick, then it isn't their fault if someone else can't. How can they be expected to go completely crazy trying to debug a 10 page long paragraph. It isn't fair to the developer.

     This is why development and production are kept separate. For this very reason. So that developers don't have to pull out all of their hair looking around for bugs. They can have their nicely separate files on the development side, and when its time to go to production, embed all the external CSS and JS into one file. Hell, you can even write a script or small program to do it for you, kinda like a linker. Those of you not familiar with what a linker is (as some who work exclusively with the web aren't), a linker is a program that takes the code that is created from a compiler and combines it into one file. Sometimes it's called a loader. Usually the linker and the compiler is the same program.

     However, none of the places I've worked at has this kind of separation between development and production. The production side is always just a mirror of what is on the development side. When a bug needs to be fixed, or a change needs to be made, its changed first on the development side, and then those files are copied over to the production side. I don't know if this is because no one wants to deal with the overhead of a "web linker", or if the thought of one just never crossed their mind.

     Of course, why stop at just a linker. Why not have a program that does more, like maintain a "CSS Smart Library", or allow developers to link notes or documentation to files (a little different than comments). Oh, or even have a built in bug tracker (*giggles like a little school girl). Imagine being able to write code once and then having a button that transforms it to PHP, ASP, Python, Javascript, or whatever else you want it to be. Or even have an optimize button that optimizes your webpages for specific browsers so you don't have to deal with ugly looking hacks. If anyone knows of such a wonderful thing that exists, please, please, PLEASE......let me know. Heck, leave a comment and let everyone know.

     I guess I just want more out of the tools I use for writing code. I did a search of web tools today and found a couple that look interesting and will give them a try. What? You mean I could build the thing that I want? Why, yes I could do that, but I'm pretty busy. I need to adjust the margins of my blog and find just the right shade of green for the background. I don't have time to do something like that!

For Loop Nonsense in Javascript

     I wrote my first program when I was 12 years old. Wow, that's 15 years ago; I'm not sure how I feel about that. I had a class that taught BASIC. I know we used Apple computers in that class, but my memory isn't good enough to remember exactly which model, only that it was command-line only. Perhaps I didn't care enough to know which model it was. The first program I wrote displayed the American flag and showed the lines of the Pledge of Allegiance. Then I wrote a "choose-your-own-adventure" game. I was to show off the game at the school's open house, but I guess I forgot to save my work from when I finished as it was incomplete, so I showed the flag instead. After the open house, I really got into programming. I cut one of my not-so-important classes to go to the computer lab and code. I spent class time handwriting code when I should have been reading a textbook or studying instead. Yep, I wrote code by hand. Sometimes, I still do. The class I cut all the time to work on my new program was Life Management, and I almost failed it! I kind of find it funny that I nearly failed Life Management because I became obsessed with writing code.

     The new program I was coding at the time (in case you were wondering), was another game. It was another "choose-your-own-adventure" game. This one had a spy theme. I was including an inventory system, money, allies (that could die if you weren't careful), and a password system so that you can pick up where you left off. The programs we made were unable to save/load data. I'm not sure why, maybe I just hadn't learn how to do that. One thing I remember from back then was using the GOTO statement. Handwriting code using the GOTO statement is not fun. For those of you not familiar with the GOTO statement, here is an example (disclaimer: the syntax written for the GOTO statements is pseudo code, I do not wish to fill my head with too much GOTO nonsense):
     
          GOTO 125

     That means jump to line 125 and continue from there. This is how control statements worked. For example:

          6  if (something = 0) GOTO 8
          7  GOTO 10
          8  line of code if the if statement is true
          9 GOTO 11
          10 line of code if the if statement is false
         11  code after the control statement

     Oh, what a mess. And this is how loops were done as well.

          5  some line of code
          6  some line of code
          7  if (something = something) GOTO 5
          8  code that comes after the loop

     That's actually not as bad to look at as the control statement really, since that example had only one GOTO. However, this article is not about GOTO. It's about the For Loop. I like to know exactly what is happening when I write code. I had always felt like there was more going on with For Loops that what meets the eye. What does this have to do with GOTO? Well, in BASIC the GOTO statement is how the loop restarts itself. In the For Loop, it's the bracket that closes the loop. But I wondered, when does the counter get incremented? When does the comparison happen? Of course these questions are pretty easy to answer. The comparison happens at the beginning of the loop and the increment happens at the end. The initalization for the counter variable happens before the loop starts the first time and then never again. But this wasn't enough for me. So I decided to play around with it a bit. I took a simple For Loop (all this is in Javascript by the way, I'm not sure if the same applies to other programming languages.):

          for (var a = 0; a < 3; a++)
          {
               alert(a);
          }

and decided to "translate" it to how I think it would work as a while loop:

          var a = 0;
          while (a < 3)
          {
               alert(a);
               a++
          }

Why "translate" it to a while loop? I feel that while (true) { } is the purest form that a loop can take. I used it many times when I needed a quick loop and didn't feel like thinking much. While looking at it, I wondered....what would happen if I replaced "var a = 0" with something else? I'm sure that it would be an error. So I tried it. I went from

          var a = 0;
          alert("Starting the Loop");
          while (a < 5)
          {
               alert(a);
               a++;
          }

to

          var a = 0;
          for (alert("Starting the Loop"); a < 5; a++)
         {
              alert(a);
         }

And holy cow it worked! I got the message "Starting the Loop", and then a message for each iteration of a. Why did it work? It isn't supposed to work like this. Every tutorial I've read, every lecture about loops I've listened to...none of them ever mentioned that you could do this. How far down the rabbit hole does this go? Are the other statements in the For Loop similar? I tried out other ways to write the For Loop, getting more and more absurd just so I can see how far I could go. All of these ended up working:

          for (var a = 0; a < 5; alert(a))
         {
              a++;
         }

        for (var a = 0; 1; a++)
        {
             if (a > 3)
                  break;
             else
                  alert(a);
       }

       for (; a < 5; a++)
       {
            alert(a);
       }

      for (; ; a++)
     {
          alert(a);
          if (a > 5)
               break;
     }

     for (; ; )
    {
         a++;
         alert(a);
         if (a > 5)
              break;
    }

    for (var a = 0; alert("printAlert"); a++)
   {
        if (a > 3)
             break;
   }

The last one only printed "printAlert" once before ending the loop. I guess since alert() has no return value it evaluates to false.

     In what situations would I need to mangle a For statement so badly? Probably none. I suppose the reason why no one ever mentions that it's possible to do this is because you shouldn't be doing this. That's what the While loop is for. However, I now feel like I understand the For Loop much better than before, even if all that nonsense above is useless 99.9% of the time.

   You can go here to view to view all the examples I put here and see them actually working.

The first is always the hardest...

     I've wanted to do a blog for quite some time now, but I've just never seem to get around to doing it. Its not that I'm too busy to do it, I just haven't done it. I've tried a couple times. Actually did write a couple of blog posts, but they never made it off of my computer and onto the internet. I could just upload those posts I suppose, but I'm a bit unsure of them, so instead I decided to write a another new blog that probably has a high chance of not making it onto the internet either. The question now is, what do I blog about? I have a good list of ideas, but I don't know which idea to start with. I want to do them all. I guess I could..but that's a daunting task, as the list is about 20 or some topics long, and deciding to do them all still doesn't answer which one to do first. So for the past couple of weeks, I'd sit myself down to finally start a blog post, put on music (usually Five Finger Death Punch or Celldweller), and then play Zuma Blitz for about 2 hours or so. I've gotten pretty good at the game, as I consistently score over 1.5 million (when using all power-ups) in the game. At least, I feel that is good. There is only one other person on my list of Facebook friends who plays as well. He beat me once.

     I think the reason why I haven't started a blog even though its something I've wanted to do is because I'm just not in the habit of writing yet. Thinking about something is different than actually doing it, and I was spending a lot of time thinking of blogging, but not actually blogging. So today, I've decided to change that. I've decided to do blogging instead of thinking about blogging. Maybe then I'lll get in the habit of it and will be able to do more than just think up topics I want to blog about. Yep, thats right, all this is just off the cuff. No planning, just typing. Ok, maybe a little planning and possibly a little editing when I finish, but I need to hit that publish button, and I need to do it before dinner time.

     What kind of topics do I want to blog about? Hmm...probably programming and software development/design topics. I don't want to never venture out from that area though, so I'm not committing to software only topics. I wouldn't consider myself a master programmer or anything, or at least not announce to the internet that I am..there are way better programmers located here in cyberspace than I could probably ever hope to be. Doing this blog is really for my own benefit and amusement. I'll do everything I can to not give out bad information or advice, but no promises.

     Who am I? If your one of the few people who end up reading this who don't actually know me, I'm Charlie. I'm about to graduate from the University of Central Florida, majoring in Digital Media and minoring in Computer Science. I used to be a Computer Science major, but then I took an arrow to the knee decided to switch to Digital Media for the Game Design courses they had. I was a programmer surrounded by students who hated programming. Not everyone in the program hated programming, just the ones I associated on a regular basis with did. I kinda wish that I could switch back to the computer science program, but I've been in college long enough, and now its time to leave.
   
     Why start blogging? Going into my final year at college, I felt that I was learning enough about programming or software development, and all the textbooks I've had to read for class just seemed to endlessly repeat what I've already known. I wanted to read something that, while not requiring me to be a master in the field, wasn't for beginners either. I turned to google to find what I was looking for, and ended up on Coding Horror, looking at a list of recommended reading for software developers. I decided to read them all, but I'm still undecided to which book to start with (noticing a pattern yet?). I looked around the site and found my way to Joel On Software, and then I looked for more blogs. I have a list of blogs I check on a regular basis now. What does this have to do with WRITING a blog. One of Jeff Atwood's posts on Coding Horror was How to Write Without Writing. That post includes a quote from Joel Spolsky about the difference between a tolerable programmer and a great programming.

The difference between a tolerable programmer and a great programmer is not how many programming languages they know, and its not whether they prefer Python or Java. It's whether they can communicate their ideas. By persuading other people, they get leverage. By writing clear comments and technical specs, they let other programmers understand their code instead of rewriting it. Absent this, their code is worthless.

     Well, I aim to be a great programmer. If the quote is true, then I need to be able to communicate well. I need to practice communicating. How to do this? Then the light bulb turned on. I'll do a blog as well. I'm usually the person that someone turns to when they need help with a programming problem among my friends anyways. I'm a smart guy, this is something I can do. Then I started doing a LOT of reading, and it seemed like the more I read, the less I knew about things. I've been told that happens though. You learn and learn and learn and then you think you know everything there is to know about a subject, and then you learn a little more and bam! You discover that you've barely scratched the surface. I don't really feel like I'm qualified to be blogging, but what the heck. I'll let those unfortunate enough to be reading this decided.

     I'm not exactly sure how long each of my posts should be. I feel like this has gone on quite a while with no real information for the reader. That was kinda the point of this first blog post of mine. It was really more for myself than anything. I was trapped in a gridlock decision of how to start this process. Starting is always the hardest part. This is especially true in programming. Once you get started and in the zone though, you can really start trucking along without thinking about it. Which is what just happened here. This post was completely unplanned, and its whole purpose was just to get me started with something. If I had tried to come up with the perfect first post, I would still be playing Zuma Blitz on Facebook probably. Hopefully, publishing this first post will be enough to get me going on this, and I won't have to do another "no subject" post. Thanks for sticking with me through the entirety of the post. I feel pretty productive right now, maybe I'll start my next post, or do that pesky Spanish homework. Right after I beat my high score in Zuma...