the zen of source code formatting

 

Source code—assuming for a moment that you didn’t already know this—is a collection of (often English) words and symbols for humans which usually is turned into something more meaningful for a computer to understand when the program is running. Each computer language has its own rules about how you order the words and symbols but most allow for a fair amount of leeway with respect to whitespace, the “rests within the melody”, if-you-will.

“most [computer languages] allow for a fair amount of leeway with respect to whitespace, the rests within the melody…”

“Source code formatting is the task of using that whitespace to maximize… something.”

Source code formatting is the task of using that whitespace to maximize… something. This of course means different things to different people. For some, they believe that source code formatting can be done only one way. To format code using any other method, in their mind, would be the equivalent of breaking some sort of law.

Others believe that your text editor knows best and should be the authoritarian on the matter. There’s usually a feature to “format document” which they believe always gets this right.

As someone who’s been coding now for almost forty years, I’d like to share what I’ve learned and to permission you to completely ignore those first two camps who would say that you must do it their way.

The Virus

In my humble opinion, nearly all of the source code formatting as seen in the world’s collection of code suffers from poor readability. And this is so because of the attitudes surrounding the topic as well as the self-imposed “leaders” and big players who believe their way is better, demanding adherence to their own opinions.

In many software development firms, this is a hot topic for debate. Coders feel strongly about how all this plays out. Outspoken individuals like Douglas Crockford (author of jslint) have even developed tools to enforce their own (wrong) ideas about how code must be formatted.

As large corporations like Google publish more in the open source area, they bring with them this kind of Draconian mindset. If you bring in their code, you’re very likely also bringing in format-enforcing restrictions which come along for the ride.

“If we think of jslint as a virus that self-propagates, then cloning a Google-published project has now infected your project.”

I have personally been held hostage for days trying to make the jslint build tool happy when I’ve been forced to use it. It’s one of the worst anti-patterns I’ve seen in this industry, to be honest.

An Innovative & Meaningful Method of Formatting Your Source Code

For me, I choose to maximize whitespace instead so that I may understand the code instantly. The more I understand the code, the less likely it is that I will later introduce a bug into this code. The faster I can speed-read the code, the more productive and happier I’ll be.

“Code Complete” by Steve McConnell

The genesis of this new method comes in part from my having read this excellent book at least twenty years ago. At the time, this was ground-breaking in its revelations of coding statistics with respect to bugs and the impact of good source code formatting to minimize their presence in code.

My method goes beyond the author’s original suggestions and is the work of a couple decades in the making.

A Practical Example

Below, I show a pair of examples. It is the same code, just differently formatted. The code language is JavaScript and is written for NodeJS, more specifically. The other examples below also are written in JavaScript.

Before (classic jslint-like formatting)

Screen Shot 2018-11-29 at 12.20.13 PM
Figure 1

After (new, suggested method)

Screen Shot 2018-11-29 at 12.22.26 PM
Figure 2

Hopefully you will see the appeal to the second method. The spacing in Fig. 2 allows us to quickly see that this section includes the creation of several variables by pulling them in from separate files and modules. Additionally, they are alphabetized to make it easier to spot accidental double-inclusions.

Given the column-like behavior and the symmetry of those “require” functions, it’s now much easier to scan down the list. It’s now a pleasure to read.

Before (classic jslint-like formatting)

Screen Shot 2018-11-29 at 12.30.22 PM
Figure 3

After (new, suggested method)

Screen Shot 2018-11-29 at 12.17.01 PM
Figure 4

Here, by tightening up the first/third activities to become single-line events in Fig. 4, it’s easier to then see that we have what appears to be a sandwich-like construction:

  1. fs.closeSync() something
  2. create a variable
  3. fs.closeSync() with that variable

The second activity now has some pretty radical source code formatting. But it follows the column rule introduced from before:  columns make assignments easier to scan.

1) The Column Rule

To sum this up: use consistent whitespace to create columns out of assignments (storing a value into a variable). This applies to multi-line assignments as well as to assignments which take more than one line to accomplish.

Create columns: “…use consistent whitespace to create columns out of assignments…”

2) Squash for Readability

If it is possible to remove vertical space so that an entire function may be reviewed in one screenful in your editor, then consider doing so. Good candidates for this treatment are the open/close pairs of file functions seen in Fig. 4. The pairing makes sense to most coders so it’s a welcome form of abbreviation.

Squash: “If it is possible to remove vertical space so that an entire function may be reviewed in one screenful in your editor, then consider doing so.”

3) Comment the Breadcrumb Trail

When there are several levels of braces in one group at the end of something, clearly comment each with judiciously-provided whitespace so that they line up as a column as seen in Fig. 5.

Screen Shot 2018-11-29 at 12.45.00 PM
Figure 5

Breadcrumbs: “When there are several levels of braces in one group at the end of something, clearly comment each with judiciously-provided whitespace so that they line up as a column…”

4) Semicolons for Readability

Use line-ending punctuation to tell one type of scope/block from another. In Fig. 5 above, fs.readdir() and fs.unlink() as function calls are each terminated with a semicolon after the ending brace. Here, I’m omitting the terminal semicolons for both the sections in the if blocks and the for loop at their ending braces.

Semicolons: “Use line-ending punctuation to tell one type of scope/block from another.”

I’m sure this one will have its critics. I would argue that the introduction of chained functions and the concept of “Promises” have created some rather interesting “dogpiles” of code at times which are too difficult to follow without this strategy.

Applicability to Other Languages

The suggestions indicated also apply to other languages. One notable caution, though, goes out to Python-related code which is fairly picky about beginning indentation style. The beginning of each line of Python marks logical blocks of codes as you might see in a matching pair of braces in JavaScript. It’s therefore critical to first make Python happy in this regard before attempting to then adhere to these suggestions. The continuation line technique seen in Fig. 4 above would not work in Python for this reason.

insight landed, still no actual photos

Let’s see… NASA’s InSight probe supposedly landed on Mars back on Monday. Visit their website two days later and there are lots of videos and photos, all of which are CGI-generated or they’re hours’ worth of employees looking excited.

Here’s one I’ve managed to dredge up though:

mars

Is that the best we can do for the US$1B price tag? Presumably, it’s a down-facing camera with a frog-eye lens.

Yet again, it feels like lies stacked on top of lies to me.

mojave, the last safe osx version?

Apple recently came out with macOS Mojave as the latest in a series of operating systems. Like most of us, you might believe that all upgrades are good upgrades. The truth is another matter entirely with respect to compatibility.

You probably didn’t know this but Apple is dropping 32-bit support in the next release.

They’ve been migrating to a full 64-bit operating system for several major versions now. You probably didn’t know this but they’re dropping 32-bit support in the next release. This is big news and it isn’t being talked about. Think of it as a means of extorting lots of money from the community of Apple developers. If those developers haven’t purchased new computers and they haven’t upgraded to the very latest version of XCode and if they haven’t paid their annual developer fees year after year then they won’t be able to exist in the next major version of OSX. Their apps just won’t work unless they comply.

What does this mean?

Simply put, perhaps a quarter of the OSX apps—especially those you have paid for—will not run anymore.

Apple’s quiet announcement

Behind-the-scenes, Apple has put up a page which warns developers what’s coming. But it’s not like they’re actually warning their own users NOT to upgrade their operating system. Of course, we’ll be nagged daily to upgrade as usual. Imagine how angry you’ll be some day in the future where you endure the typical hour-long upgrade only to find out that your Adobe Photoshop doesn’t run after the upgrade. Typical of Adobe, they’ll likely end support for the version of their software that’s only 32-bit and you’re caught in the crossfire.

How to tell

Here’s how to tell if a particular app won’t work with the next major release of OSX:

Apple menu -> About This Mac -> Software -> Applications -> select application -> 64-bit: yes/no

In this example, we see one of the pieces of programming provided by Adobe indicates “No” in that field meaning it will stop working soon.

Screen Shot 2018-11-05 at 8.41.19 AM

You can adjust the sizing of the report’s columns and then to sort by that 64-bit heading to show a list of the ones which won’t work.

Screen Shot 2018-11-05 at 8.49.41 AM

You have to laugh when you seen two of Apple’s own apps in that list and they’re responsible for their updates of course.

apollo 11, the first lie

Old Lies

Mark me down as one of those who understand that Apollo 11 didn’t go to the moon as publicized by NASA. I’ve known this for a while now but even this video should make sense to some of the people out there who thought otherwise.

As heard in the video, there is clear scripting going on with the astronauts. An extra off-screen voice is heard coaching them when they’re supposed to respond (mimicking the distance delay), instructing them how to fake the Earth’s distance by ricocheting its image off a far glass and by darkening the inside cabin as well as introducing a fake solar terminator. Unfortunately for NASA’s credibility, they accidentally released raw color video which still included all the prompting, planning of fakery and references to later video processing which was to occur.

But of course, they knew back then that they couldn’t survive the journey because the Soviets knew this. In typical Russian style, they just secretively sent many cosmonauts to their death. News of this made it back via spies to NASA of course. Rather than to admit defeat NASA just chose to completely fabricate a story of success.

In a way, it was just bad timing. In the beginning of the sixties, they actually thought that they could make a trip to the moon and back. It wasn’t until the Soviets had sacrificed their own people enough times that the Americans realized that this was a losing game. Having made bold claims to the world about what we were capable of doing, they didn’t feel like backing down from such earlier bravado. So they faked it, nearly the entire thing. The Apollo astronauts just orbited the Earth the entire time, having earlier done the lunar videos on a stage at Disney. Stanley Kubrick’s recent sci-fi movies made him the obvious choice as director; his innovative front screen projection technique was used for the lander footage.

Current Lies

Even to this day, faked videos are being produced by NASA for unknown reasons. That same guy wire technology is still being used to give a false sense of weightlessness.

When asked why it’s difficult to go back to the moon, NASA’s own employees have suggested that “we don’t have the technology to go to the moon” because we destroyed it. Really? That’s the equivalent of “my dog ate my homework”. It’s a 12-year-old’s lie to their teacher.

NASA’s own engineer suggests that they still haven’t figured out how to get past the Van Allen Belts. Really? As if we didn’t already know that you guys couldn’t have gone to the moon in the 1960s because of this.

When George Bush Sr. visited NASA on a tour, I guess everyone was so preoccupied that they forgot to stop making a fake ISS video on a green screen in the background and this was totally published. Oops.

The Mars Viking Landers

According to NASA, the Martian landscape was red and a forbidding landscape. I’m sure we’ve all seen images like this.

viking-lander

But according to one employee, the feed suddenly went dead right after seeing two people in spacesuits doing repairs as seen here.

viking-lander-being-repaired

So we’re left with one of two eventualities: either all this was filmed on a backlot somewhere and 100% faked here on Earth… or the cover story that Mars isn’t inhabited already by us is simply a lie. If this were filmed here on Earth then why the need for a spacesuit or helmet at all? That pretty much leaves us with the other option, the one in which a private version of NASA has been on Mars for some time now.

The Mars Mining Corporation

Marine whistleblower Captain Randy Cramer indicates that he spent nearly an entire 20-year tour on Mars in support of a private mining company located there.

So Why the Lies Now?

I suppose there comes a time when your lies just catch up to you. NASA can’t just come out and say they lied to us in the sixties. For the same reasons, they can’t just suggest that we’ve reasonably managed to secure Mars now for a private corporation. As liars in league with liars, they can’t break ranks and simply tell the truth. Telling us that public dollars have benefited a single corporation’s stockholders just wouldn’t make people happy when you get right down to it.

Until the public in the majority understands the scope of these lies and then directs their anger at NASA and our own government, we’ll just continue to be fed more lies by these people.

recycle, re-use, re-purpose – part ii

Continuing with the work to re-purpose a computer mouse as a filament movement detection device, I designed and printed some parts for this. The bottom part is perhaps 5mm in height from the spool itself and is reasonably a good distance to see changes.

I’ve edited the earlier Python script which originally detected the scroll wheel button; it’s now detecting movements of Y as if the mouse were being moved on a mousepad. It will only do this if I take the white assembly and move it around on a patterned surface, however.

To help the mouse detect movement better, I’ve tried using both grid paper and a polar version of same. I don’t love the feedback loop that’s going now. I’m sure there’s a better way to get this movement detected all the time, though.

IMG_0115

IMG_0116

IMG_0118