Saturday, August 26, 2017

Code That Reads Like A Novel

I’ve run across this more and more, recently – developers who want code to read like a novel.  In other words, they want an entire application’s logic to be in one script – maybe a couple more, if the app is really complex.  And we’re not talking concatenated files, here (I’m all for those); the design should result in one script. 

I think this is so problematic. Multiple contributors to a document typically makes it harder to read.  Each dev has his or her own style, and when you start to mix them, it just becomes weird and hard to follow.  When I first started running into code like this, I adjusted my style to fit what I saw.  I thought it was a good idea.  Ten months down the road, however, when there was more work to do, I was lost.  I couldn’t remember what I was trying to do, or even why.  It didn’t save time, or make the app more maintainable.  The added (unnecessary) frustration didn’t help, either.

Changing working code often introduces new bugs.  How many times have you made a quick fix, just to later find out that you created another problem?  Happens all the time.  In small, decoupled scripts, that’s practically impossible to do.  If it turns out that something is wrong with your code, you can be sure the error is in the document that you created/altered.  No need to go searching through 1500 lines of code to figure out the issue.

Forget about replacing libraries, or even large portions of functionality.  That’s a guaranteed re-write.  Search and replace won’t save you when you when there are 150 versions of the function name you’re trying to update/replace.  In writing an elaborate to-do app, for example, you’re inevitably going to use some variation of the word “task” at least 100 times.  Sometimes it’ll be in comments.  Sometimes it’ll be part of variable names.  You may even find it in include-file names. 

Lastly, (I know I’m getting a bit long-winded here), unless you’re given a complete build, most tickets are for bug or feature requests.  In either case, you don't need to know how the entire app functions to solve the problem.  You just need to know where to implement your solution.  I almost always create new scripts, once I’ve reached this point.  When I realize I’ve misunderstood the requirements, I just go directly to that doc, and make changes. 

Ultimately, these long scripts make code more brittle.  I’m probably preaching to the choir, for the most part.  It seems most of us prefer to have our code broken down into modules/components that are then assembled in a main script (router, App.js, etc.).  Still, there are quite a few who disagree.  I’m just supporting my position.

As always, let me know what you think. 

No comments:

Post a Comment