Code Responsibly (2015)

Control YourselfWe are stuck with technology when what we really want is just stuff that works.

Douglas Adams, The Salmon of Doubt

More often than not I’ve had to deal with projects where I sincerely wondered whether salespeople and upper management – those that charge admission for the voyeuristic tendencies of the public in relation to technology – understood the implications of decisions. Examples abound. Planned obsolescence of a business infrastructure based on a technology tree. Coding one’s business into a corner. Complaining about the spaghetti code but forcing the conditions where all programmers can do to keep their jobs is make meatballs (features) and slathering the thing in sauce so as to keep those that sign paychecks appeased with something… resembling… something palatable. The list goes on.

Somewhere in the 1990s, Free Software and Open Source came along and put programmers in charge of much of the business process. Because of experiences I’ve had over the years, it was easy to say, “hey, this might fix everything!” Years of experience, though, made me bite my tongue because… well, because programmers are mostly interested in writing code. It’s rare to find a programmer that is interested in actually creating a product. Just as there are no unfinished poems for poets, there are no unfinished programs for programmers.

This has haunted Linux. Granted, Linux at its core has a benevolent dictator that keeps feature creep and feature tsunamis under control – but the desktop Linux never took root as much as it could have because software developers aren’t as good at keeping things simple. Frankly, in general, we suck at it. It’s not a bad thing. It’s not a good thing. It’s the way it is. There are outliers, of course, but those are rare. I’m one of them and it’s because of something quite simple I learned as a Navy Corpsman:

First, do no harm.

Harm is a subjective term. There are even people who appreciate the common understanding of the word as pleasure though this is a family friendly blog and we won’t discuss that much. Let us say that, generally speaking, there are almost no people on the planet who would wish to have harm propagated against themselves. Yet software developers have a tendency to do it every day. I’ve done it and, on much rarer occasions, I can catch myself doing such things because I’ve learned to identify them.

That’s why I really enjoyed Paula Rosenblum’s article, ‘Is Software Quality Going To Hell In A Handbasket?:

…Can anyone yet understand why the MS Office interface has changed completely twice in the last three releases? How many hours of productivity have you lost hunting for menu items that you knew by heart last time around? And do we even want to start talking about Windows?  Not today. These posts are only supposed to be so long.  Let’s just say when your Executive VP banker brother-in-law calls to ask you how to print a document in Windows 8 you know things have just gone silly…

Paula completely nails it, and that’s just a piece of the article.

Simplicity is really the key. Yet simplicity isn’t that easy when expectations are constantly evolving. The only way to actually assure a good balance of features and meeting user expectations is something that most software developers suck at: Communicating with users.

It’s almost akin to having Marines who were naughty getting stuck with KP duty – where they cook for other Marines. The Marines don’t see a flaw in this logic.

To make matters worse, businesses are also not that great with the balance – and in being bad about the balance, they often spend more money than they would have to in chasing their tails – or as they see it, catching that thing that’s oh-so-close-all-the-time.

Programmers do it to themselves. Businesses do it to themselves. Worse, both can propagate it on others – and often do.

First: Do no harm. Code responsibly. And use the right technology – just because you’ve invested heavily in it doesn’t make it right. The world has been littered with the bodies of those that meant well while reinvesting in bad debts.

After all, the income you save may be your own.

Image at top left courtesy Flickr User JOSE VICENTE JIMENEZ RIBAS through this Creative Commons License. Enhanced by Zemanta

Evolution: Process Trumps All

3D view of Mar03wjc1bOnce upon a time, software was sold on disks that were actually floppy. They were encased in boxes, with user manuals.

Then the disks were no longer floppy, but they were called floppy as a sacrifice to the Gods of Inaccuracy.

Then the Internet came along, and you could buy the boxes over the Internet.

Then you could download the applications over the internet when you purchased them.

And finally, Software as a Service (SaaS) came into being, and all was basically the same only faster (and with significantly worse documentation).
And the people were generally as miserable as they were, and could be disappointed at a faster rate when they found bugs, or when systems went down, or when their internet access was sloppy.

The real difference between competing companies now is how they produce and maintain the software. That’s the process.

Bugs happen. How fast can the bug be fixed, without introducing new ones? That’s the competition. That’s where competing companies actually should be competing, because the faster a company can fix bugs, the faster it can implement things as well.

That boils down to Software Process. And that’s why Agile, Lean, DevOps and so on are so important.

Because nobody is ordering boxes from the back of magazines anymore and getting it in the mail a few weeks later. They want it now.

If you don’t even have a software development plan (SDP) for a project, you’re already behind.




Getting Past the Mystery of MVC

One way for Software Engineers/Developers/Programmers to impress the hell out of Managers, Directors and Executives is to confidently shoot acronyms at them in rapid fire. Dilbert is rich with this; since the late 90s I’ve sometimes tossed ‘EIEIO’ into the mix when I heard it being abused.

MVCOne of these acronyms is MVC. It’s really simple. See the image on the left? It’s that simple. And it’s not new by any stretch. It’s great for architecture of small systems, and done properly can do well for much larger systems – if you understand how to define the Model, the View and the Controller.

I say it’s not new. In fact, it was introduced in 1978-1979 by Trygve Reenskaug and others for the Smalltalk-76 programming language at the Xerox Palo Alto Research Center (Xerox PARC). You can figure that it has been around almost 40 years, and that it’s from the same era as the mouse and the graphic user interface (GUI).

As a concept, it’s fairly solid – and used properly, it can be powerful. But it doesn’t mean that every system should be MVC – in fact, with application development the way it is these days, a lot of systems probably shouldn’t. Why? If you’ve got multiple application programming interfaces (APIs), you may be going down the rabbit hole into complexity and making software entropy that much more accelerated within your Software Development Life Cycle (SDLC). This article makes that point quite well and offers alternatives, though it stops before getting to some of the conclusions I draw.

So let’s get to the crux of MVC. It’s one of many architecture patterns out there, and the main thing that really needs to be talked about in the context of MVC it’s about implementation – languages and technologies that allow for proper use for MVC. Some don’t give as much flexibility as others.

And MVC isn’t always the answer – more often than not, in the last 2 decades, I’ve seen it used as the straws a drowning application clings to. It’s not bad – it’s not good. It depends on how it’s implemented, and proper implementation in a complex and open system – which describes most – can be outright scary.

A good Software Architect knows these things. A good software architect puts the complete system requirements ahead of the architectural skeleton that is to be and decides on the architecture – while planning for future growth.

Is MVC right for you? I’d say mostly yes. But don’t think it’s new. It’s the architecture that has lasted 40 years and has brought us the applications we have today. Is it the right architecture for the future of your systems? That is a question that should be posed to architects to challenge them.

Your mileage should vary if you’re doing it right.


So You Think Documentation Sucks.

GNOME doc sprint 2013I had a few conversations today involving documentation in email and otherwise. One was griping about someone else not writing documentation. I had someone saying developers don’t like to document, which is a fair statement, but it’s like saying that they don’t like holding heavy bricks over their naked feet. That’s the equivalent, and if you’ve been around a while, you know that. Even the best coders with perfect memory don’t like explaining their code to others over and over, and it’s a blessing for them in that way. 

Later that day, that person griped about someone writing documentation because they needed something done fast.

Another person and I were going back and forth by email about documentation (oddly related to the same thing), and the perspective presented was that automated documentation was the way to go. I’ve seen automated documentation. Developers work around it. “Oh, I have to put something above the header for my class. I’ll write something witty”, instead of accurate, or both, and 3 years later you get hired in to stare at functions named after this person’s cat, or SuperDuperIntegrator, or – my personal favorites – the Monty Python characters (seen it). That’s just one of the many problems.

The idea behind documentation is that things should be easy to find, easy to read and comprehend if your IQ is above 90 and below 300. It should be accurate, clear and concise – or as close as you can come to it.

Over the years, people taking large amounts of your time to explain the same documentation over and over again causes you to write better documentation. You may not be the best at writing it, but when you’re pestered by people over the years, you end up spending more time about the questions that will be asked and answering them in advance. I’m not kidding. What’s more, it actually helps you with your coding because of it because you’re thinking as you do it, “How do I explain this?” It’s a code review in your head by people’s past implicit criticisms of your documentation by making you repeat yourself.

Documentation becomes a habit.

Or you can keep griping about the lack of documentation by not writing any. See where that gets you. Frustrated teams, tired of having to research everything goddamned thing as if it were the first time, every time. That makes it a bit harder to hire people, because the people who leave aren’t going to be happy. Maybe you’ll be one of those people to go work in a cushy job where there is great documentation (the El Dorado of career software engineers).

Good documentation assists software processes. Requirements traceability alone can become easier. Distinguishing scope at a code level becomes easier. Dependencies are easier to police. Design decisions can be made understandable with things like, “We did it this way because we were rushed for a prototype.” It necessarily slows development because development sometimes needs to be slowed – QA assures quality, software engineers put the quality in and quality, even with a peer review process, is adversely affected by lack of time and in a culture like that the software complexity increases until you’re swimming in a sea of software entropy. Code so fragile that a glance from a user can level it.

Yeah, documentation sucks. I actually hate it though some people seem to think otherwise. Documentation is anticipating needs in the future while describing the present and, if done well, the past as well.

If it was hard for you to figure out, it will be hard for someone else. Document it. If it was easy for you but after a moment’s pause while writing the documentation and looking at the code again, you’ll think about the how, why, what, when, where and who of what you’ve done and may even see things you have missed or see you don’t even understand.

Yeah, documentation sucks. But a lack of it is much, much worse, and bad documentation is almost as bad.