Doomed to Refactor

Those who don't refactor bad code are doomed to repeat it.

- Me, Just now

Yesterday, I tried to create a single component comprising several input fields for a person's name. That way, anyone can just drop in this component anywhere and it should look the same everywhere. I spent all day writing it The Right Way™ and in the end, some hacked-up validation logic which didn't follow framework convention pretty much screwed it up. Now, I was forced to (gasp) copy-paste my logic everywhere instead of housing it to one component.

Convention over configuration

In software, there is no such thing as The Right Way™.

- Another developer, yesterday

This... made my blood boil honestly. But I forgive his ignorance and spared him the lecture. Sure, there is no The Right Way™ in writing software, but there is such a thing as a "proven and tested way" which is almost as good as The Right Way™. There's even a word for it: Convention.

It's like having to drive a nail in the wall. Anything from a nail gun, a slipper or even a laptop can drive a nail to the wall. However, I wouldn't dare using my laptop, A slpper would be too flimsy, and I would probably purchase a nail gun and potentially shoot myself in the foot, literally. That's configuration.

On the other side of things, there's an invention called the hammer. It's not the most elegant nor efficient tool for the job. However, it's probably the first thing that comes in to mind, I probably have it in my toolbox, I know how to use it, and everyone else uses it. That's convention.

TL;DR: Follow convention. Use a hammer demmet!

It's more than just cascading stylesheets

Great, you're now just adding to the muck that it already is

- Yet another developer, around a month ago

So... CSS. Another enemy of developers. I have heard battle stories from novices as well as veterans. From "that's why I moved to PHP" to "Oh, CSS isn't my greatest strength" - I've heard them all. CSS isn't the greatest thing created. However, the only thing that seriously makes CSS terrible - context-specific naming.

If I write css like .registration-page .registration-link{color: #000}, I would assume that registration links on the registration page are black? But what if I have registration links on other parts of the site? I wouldn't want to add another selector, otherwise CSS will be playing catch-up with HTML as I add pages. Removing the first class would mean globally applying black to all registration links, which I might not want.

If I just wrote a utility class .fg-black{color: #000} and stuck it in the HTML that needs it, problem solved. CSS doesn't have to play catch-up with HTML. The only time I'd write CSS would be when I need additional utility classes or fixing existing ones. Otherwise, it would stay idle as long as it's complete enough.

TL;DR: CSS should be context-free.

Why event-based decoupling is terrible

I once had this argument with a senior developer. That developer told me to use the Flux pattern. I, on the other hand, opted with event-based decoupling. Now, it wasn't long before I saw the benefits of Flux and started to promote it. However, I always wonder what would have happened to me if I continued down the road of anonymous event-based decoupling... I just had to ask.

Now I'm stuck untangling a huge app which happens to use the very same pattern I used to side with. Yes, event-based decoupling. Making it worse, events are hardcoded where they are fired, making them hard to audit. This means there's no central location to look up for events, and yes there was also no documentation on what events were fired at all.

It's like being caught in the crossfire of a 100-player Quake 3 free-for-all. Events fired and forgotten everywhere, there is no actual flow of data. Heck! I can't even determine why an event fired twice or an endless async loop happened!

TL;DR: Invest heavily on your app's architecture.

Semantic HTML is still valid

Semantic HTML is still valid in my opinion. Why? Take for instance this real-life code I encountered in one of my adventures. Does this make sense?

    <div class="col-70">
      <input type="text">
  <!-- more of this repeated -->

No. It doesn't. <fieldset> is supposed to group cohesive input fields. It's not a separator of individual fields. <legend> is supposed to name the fieldset it contains, not label the input - that's what <label> is for. .col-70 would make sense if it was 70% of fieldset's width... but there's no other .col-xx in the stylesheet. Making it worse, <legend> is styled with 30% width. Why wasn't a .col-30 created for it?

    <legend>Personal Info</legend>
      <div class="col-30">
      <div class="col-70">
        <input type="text">
  <!-- more here -->

Now this makes more sense. There's a clear and proper usage of HTML tags. There's consistency in the utility classes. And reading it as is just makes sense in that nothing is implied. Everything's just there.

When I do a <p>, be damn sure it looks like a paragraph everywhere.

- Me, when someone else was doing CSS

Additionally, writing plain markup with very little context-specific markers (IDs, classes and attributes) will make it easier to move around. For instance, reusing the same address form in personal info in the billing section. Sure, I can copy-paste the thing. But if I had context-specific markers, the markup will contain markers that pertain to personal info which makes no sense in billing. Additionally, I'll potentially carry over styling and logic from personal info that I may not want in billing info.

TL;DR: Write context-free markup as much as possible.


My (mis)adventures in programming just became more interesting. Meeting weird people, discovering awfully terrible code, and real deadlines. Argh! Software would have been more interesting if only developers wrote their software with love and care. I guess not all developers do.

Whatever. Now I've been granted an opportunity, it's time to show them what I was famous for - refactoring. Refactor early and refactor often. Those who don't refactor bad code are doomed to repeat it.

architecture refactoring

© Joseph Descalzota