Chronicles of Broadcom – How NOT to code

I have been writing a lot lately, unfortunately not in direct relation to my blog or public persona. I have been unable to code properly in the last month and it has been wearing my managers thin. We are trying to add a couple seemingly simple modules to a perl cgi application and I’m running into the age old problem of code complexity being the bane to all existence. I ranted previously about how goofy the code that the previous developer chose to use for the template engine, and I wish that were the end of the train. I have hit a weird stand point. It seems like adding anything to this is a pain. Let’s take a step through the code, together.

Posting a form
This should never be a hurdle on any web project, considering the immense amount of work your web browser handles for you. Miraculously, on this app it is not just a hurdle it’s a fucking mountain. It seems like every step that I take up the hill towards completion is like moving along an ever thinning ledge along an ever steepening cliff. The general idea for the post is that you accumulate the form data and send it via a POST method to the server so it can handle the values and it will then parse its parameters and do some craziness and respond. Well this application is trying to follow this pattern with the unnecessary step of using AJAX to handle the POST parameter string is created manually with a long array of statements that look like this:

returnstr = returnstr + "varname=" + document.getElementsByID(‘varid')[0].value;
returnstr = returnstr + "varname2=" + document.getElementsByID(‘varid2')[0].value;

Aside from attempting to post this code on thedailywtf and laughing for a few days I have to keep in mind that I get to work with code of this caliber on a literal daily basis. That means that my job gets to be more difficult with each passing day, and quite unfortunately I have to struggle to get through this shitty code. I remember talking to the original author some time ago, before I had seen his code. The two of us spent a good two hours once or twice a week complaining and laughing about shitty habits that had been conducted by other members of our development team. Here we are, a year or so later, and come to find out, he is now a hired developer and exhibiting the same lack of caring or understanding that the previous developers we had been laughing about together had shown.

The reason this came up is because I was asked to do something that seems to be quite simple – Add a file upload field to the form. The problem is that AJAX cannot post files, it is what we call a sandboxed language. In order to post a file you need to post it the regular way, allowing the browser to handle all the security and non page related interaction. It’s amazing to me how complicated adding this was. Rule number one in this development team is to never change the users expectations – i.e. I cant change the way this application works at the fundamental level, and unfortunately that means leaving the crazy shit of an AJAX post alone.

I spent the better part of a week reading through a book on jQuery which is the corvette of AJAX libraries. This was triggered by the previous author saying I should leverage it, so before I jumped into using the library’s documentation. The good news is that the library is amazing, the bad is that its not being used anywhere in the current code. Instead I see code like the above everywhere.

The ultimate solution was to add a hidden iframe and click a button in it to submit that form each time the response was given from the previous post, but that too came with its issues. Ultimately it achieved the level of craziness that I needed it to, but not before causing me to have to grow a beard and shave it off, twice.

When someone tells me about their new templating engine I usually ask to see a demo of the code used to create a page using it, for the express purpose of understanding its syntax. My PHP development history has included a number of botched template engine attempts, hence my choice to move to leveraging the tried and true frameworks from the market. So I know what shouldn’t be done. Perl has a number of template engines for HTML/CGI development so imagine my surprise when I stepped into the code and saw something similar to this:

use CGI;

our ($varNum1, ... , $varNum9);

sub init_ship
my (@L) = @_;
$varNum1 = "<input type='text' value='" . $L[0] . "' />";
$varNum9 = "<input type='text' value='" . $L[8] . "' />";

sub init_report
my (@L) = @_;
$varNum1 = "<div class='label'>" . $L[0] . "</div>";
$varNum9 = "<div class='label'>" . $L[8] . "</div>";

my $q = new CGI();

if ($q->param("page") eq "Report")
else if ($q->param("page") eq "ship")

The printShip() procedure then prints out a heredoc with a block of HTML that makes reference to $varNum1 -> 9. Is that templating? I don’t feel that it is, and my experience with templating is leaning me towards saying absolutely not. Its quite frustrating when there is an issue with formatting or change to a string, which I have had many of this caliber, which requires me to literally do a search and replace through the code because while this only has two levels of variable aliasing the application I am working on uses four. Adding a new field is that much more complicated. If this is a template engine, it is far too complex for any of our needs.

Template engines were created to help with segregation of data from presentation, in a similar method to what CSS provides on top of HTML. The amazing thing is that the cool majority of the engines that are available to us are all sub par, only there to be called template engines when in reality they are simplistic overly complex buffers or assignment trees.

Adding a block to the template engine that I was provided with here required me to…

  • Declare the variables up on the top, explicitly
  • Make 8 additions to each of the four functions, defining/assigning values to be printed
  • Navigate to the three, yes three, different output blocks and make the appropriate html and css entries to make sure the values are displayed properly

Other No-No’s

Fortunately enough for you and I, hard coding is a well known problem. Most developers push themselves not just to avoid coding anything explicitly into code but often to the point where they hide every variable away in the database. Although, I have read essays from some of the popular faces in development arguing about the usefulness of doing so I still stand by the maintainability issues related to such things. When you have a username or database location change, or if you have multiple environments, as many of us do, how would you go about changing things?

  1. The so called hard coding path, is to do a search and replace to replace whatever is going on.
  2. The second path is to use variables and create a configuration file that handles the actual value assignment. The benefit is that you only have to make a change in one location.
  3. An extension to this second path is to put a switch that is dependent upon an environment test into your configuration file. You can create new environments as you wish and the most important part of this is to realize that all you have to do is change the location of the application and it will perform accordingly.

I am becoming more and more tied to the Sbx/Dev/QA/Production development pattern, so this is the only option for me.

In the code that I am developing in there are a number of no no’s beyond hard coding. A lack of function calls is one. Encapsulating groups of commands that are executed numerous times is one of the most important things to deal with because if you don’t take care of wrapping functions up you will ultimately end up with the dreaded maintainability issue of having code duplication. Everything in this application is procedural, except for triggering and assigning the template engine or using other modules for what that’s worth.

Commenting is something that is always missed in any developers education. The rush to push a linked list or some new struct into the teachers inbox is never going to be compatible with fully documented code. I could easily rant for twelve pages about the importance of code commenting. I am remembering a specific case where I was working on a simple domino game a lady came up to me with a question. As she lifted her paper the only thing that my eyes could land upon was the huge header that spanned two pages. I felt the radioactive green of comments burning into my eyes! When she finally noticed my jaw being slack she asked me what was wrong and I did my best to be kind – “What the fuck is this shit? Do you realize the concept of commenting is not to give someone a story, but to explain to someone about what you are doing immediately?”

It is increasingly more important to have a developer write self documenting code. As applications expand and become more complicated it is intuitive to me that this means that development is becoming more difficult. It follows that if you can help anyone to reach the goal of using your library or code base and doing so with a positive result you absolutely should.

Working corportate has been a hell of a learning experience, but I still stand by giving credit for all of my skills and abilities to the open source projects that I have used and run along the way to landing at Broadcom.  I think I have come a long way from the incomplete and haphazard patterns that every developer initially begins their coding childhood with into the analytical and detail oriented developer that I am now and hope it will continue for a good long time, far into the game industry.

  • Barbara

    Keep up the good work.