Simplicity, entropy, and the programmer's struggle

RobertK · 01-16-2008, 03:33 PM

These four important letters make up an acronym, one of the most important for software designers.

Keep
It
Simple,
Stupid

Some people like to play around with code obfuscation, but outside a competition in obfuscation the learning experience is limited. To what? Learning why you don't want to obfuscate, of course! This doesn't mean you have to write "stupid code" but that you shouldn't purposefully write obfuscated or clever code.

Any code of your own that you haven't looked at for six or more months might as well have been written by someone else.
Eagleson's law
Two things are infinite: the universe and human stupidity; and I'm not sure about the universe.
Albert Einstein

I'll give you an example. Lately I've been writing an installer script for my own project, because it has certain variables that change per-server. So I just decided to start with the installer to set up all the initial accounts and settings, so I didn't have to write a tool.

Lately I've been doing a lot of reading about Object Oriented Analysis & Design, and have finally gotten my head around the base concept of MVC. I've heard, read, and tried to code through such explanations before, but they never made sense to me. Until I was reading through a book called: the Pragmatic Programmer. A better book about programming technique I have never found.

My installer progresses well, of course. I'm not an amateur, and some of the functions I struggle with are troublesome due to being out of practice. But now my script has reached four pages in length, and is about prepared to stretch to two additional pages to finalize installation settings. So? I've written everything in one script, index.php, and while the process is 90% automated---it is getting hard to distinguish between sections.

I have a php "header" where all the logic occurs procedurally, and can override any other part of the settings aggregated so far. Sounds a bit strange, I guess, but it works just fine. But currently it is an ugly if-then-else statement that ought to be a case statement. I am starting to lose track of the logic paths my own (small) installer is taking.

This leads to troubleshooting as I typo something little, and lose track of what it begins to impact. The script is less than three hundred lines, but even commented parts of the source are getting nebulous. Then I have to maintain all the HTML code below, where all the results and pages are all mashed into an ugly template.

This is just one script with many subsections listed all at once, with a template beneath it with php if-then-else logic dictating which portion of the templates are valid for each page.

Switching to multiple pages is a choice to get me out of this mess, but so is switching to an MVC model. Admittedly an installer isn't something important enough to have an MVC model designed for it specifically, but anything is neater than just one mashed-up script!

The competent programmer is fully aware of the strictly limited size of his own skull; therefore he approaches the programming task in full humility, and among other things he avoids clever tricks like the plague.
Edsger Dijkstra
Simplicity is prerequisite for reliability
Edsger W. Dijkstra

Dijkstra warns us about cleverness. I can freely claim my script is quite clever, because I do think it is. But the cost of that cleverness is at understanding and robustness. Clever or not, it is hard to maintain, expand, and even troubleshoot. All it takes is one unforeseen circumstance, one incorrect statement, or one little mistake in handling of data, and you're off on a track without a map to get back. Worse, you may not even know how you got there, and so have to track it down.

These things get ugly and become maintenance nightmares the larger your scripts become. Yeah, my installer script is small and bad enough for its size, but as I finish it I will struggle to keep it fit. And just three hundred lines at that.

What trouble will you have with your big project, that you might have coded cleverly and mashed together inefficiently (for understanding, not execution, silly)?

I'm going to take steps now to fix my installer before I even finish it, because I know that to prevent software entropy I must proactively repair my code. I've seen the problems, so why let them lie? The KISS principle tells me to simplify things, but I also don't want to try and dumb things down. I'll leave those things that should be complex or clever to be so, but I'll tone down everything else.

Einstein gives us excellent encouragement in good software design, and Feynman gives us a stern warning about ourselves:

Make everything as simple as possible, but not simpler.
Albert Einstein
The first principle is that you must not fool yourself - and you are the easiest person to fool.
Richard Feynman

Never compete with yourself to write the most clever code you can, because by definition you won't be clever enough to debug it.

Write simple, understandable, tidy, and above all: maintainable code.

This is my thought for the day, and I'll leave y'all with that. Try not to be one of those that my signature directly applies to.

codefreek · 01-17-2008, 08:18 AM

This was fun to read :)
thank you..

RobertK · 01-17-2008, 12:54 PM

You're welcome, I'm glad you enjoyed it.

Karl · 01-17-2008, 05:47 PM

Nice article I couldn't agree more with what you're saying. I also strive for simple easy to understand code, mainly due to the exact same reasons as yourself. A word of warning though, when you refactor your existing code, do it in very small stages, refactor a function here, test, a function there, test, etc. I didn't follow that once (about 6 months ago) and I'm still piecing the project back together now :(

RobertK · 01-17-2008, 05:57 PM

Thanks for the advice Karl; I don't intend to burn it all at once.

In this case it'll be a half refactor as I implement Smarty, then split everything into its own page of tests. I think I can store stuff safely within the session, if only temporarily. (Not like I'd purposefully leave DB details in there for awhile!) I've gotten a vague idea of what to do, and how to do it, if I do go MVC--but that's still advanced to me at this stage. I can refactor into MVC in the future if I so desire.

Eeek · 02-11-2008, 11:24 PM

I always wondered what the last S in KISS was for. lol

ReSpawN · 02-12-2008, 11:22 AM

... Knights In Satan's Service.

That's what the band means anyways.

As for the last S in this KISS version, I can so relate to that.

I thanked you before, but I forgot to place a real reply, so this is it.

Thanks! Good article.

Aaron · 02-13-2008, 11:41 PM

When you say that you should keep it simple, you should expand that a little further... keeping the method you use to execute the code simple is good, but keeping the bells and whistles simple is kinda not-so-smart :P

Like, a log-in... Making the security simple might end up with you getting injected with SQL.

RobertK · 02-13-2008, 11:48 PM

As I summed the document up, maintainability is the ultimate goal you should try for. Simplicity is a great tool to get things there, but it isn't the only one. Documentation, tidy, and understandable (code that isn't cryptic) are also helpful tools. The point is to keep things usable and maintainable over long periods. And as Einstein said: "Make everything as simple as possible, but not simpler."

It was there, if you read and don't skim the document. However the point was the struggle between simplicity, entropy (chaos, disorder), and the programmers struggle with each. Oversimplification versus Obfuscation ... and how you could possibly maintain either.