A Guide to Commenting Your Code

I spend a lot of time working with code that someone else wrote. The code has lots of comments, but they actually do little to improve the understandability of the work. I’m here to provide a concise set of examples to demonstrate the proper way to comment your code so that those who follow will be able to understand it easily and get to work.

These examples are in php, but the principles transcend language.

WRONG:

// get the value of the thing
$val = gtv();

RIGHT:

$thingValue = getTheValueOfTheThing();

WRONG:

// get the value of the thing
$val = getTheValueOfTheThing();

RIGHT:

$thingValue = getTheValueOfTheThing();

Oh so very WRONG:

// Let's get the value of the thing
$val = getTheValueOfTheThing();

We’re not pals on an adventure here.

RIGHT:

$thingValue = getTheValueOfTheThing();

You might have noticed that so far all my examples of the proper way to comment your code don’t have comments at all. They have code that doesn’t need a comment in the first place.

Computer languages are not created to make things easier to understand for the machine, they are to make sets of instructions humans can read that (secondarily) tell the computer what to do. So, if the code syntax is for the benefit of humans, treat it that way.

If you have to write a comment to explain what is going on in your code, you probably wrote it wrong. Or at the very least, if you need to write a comment, it means you’re not finished. I write many comments that start TODO, which my tools recognize and give me as a to-do list.

Stopping to come up with the perfect name for a variable, class, or function is an important part of programming. It’s more than a simple label, it’s an understanding of what that symbol means, and how it works in the system. If you can’t name it, you’re not ready to code it.

There is a special category of comments in code called doc blocks. These are massive comments above every function that robots can harvest to generate documentation. It’s a beautiful idea.

Here’s my world (not a standard doc block format but that’s irrelevant):

/*
|--------------------------------------------------------------------------
| @name "doSomething"
|--------------------------------------------------------------------------
| @expects "id (int)"
|--------------------------------------------------------------------------
| @returns "widget"
|--------------------------------------------------------------------------
| @description "returns the widget of the frangipani."
|--------------------------------------------------------------------------
*/
public function doSomething($id, $otherId) {
    $frangipani = getFrangipani($id);
    multiplex($frangipani, $otherId);
 
    return $frangipani->widgets();
}

The difficulty with the above is that the laborious description of what the function does is harmfully wrong. The @expects line says it needs one parameter, when actually it needs two. It says it returns a widget but in fact the function returns an array of widgets. If you were to try to understand the function by the doc block, you would waste a ton of time.

It happens all the time – a programmer changes the code but neglects to update the doc block. And if you’re not using robots to generate documentation, the doc block is useless if you write your code well.

public function getFrangipaniWidgets($id, $multiplexorId) {
    $frangipani = getFrangipani($id);
    multiplex($frangipani, $multiplexorId);
 
    return $frangipani->widgets();
}

Doc blocks are a commitment, and if you don’t have a programmer or tech writer personally responsible for their accuracy, the harm they cause will far surpass any potential benefit.

I have only one exception to the “comments indicate where you have more work to do” rule: Don’t try this at home.

public function getFrangipaniWidgets($id, $multiplexorId) {
    $frangipani = getFrangipani($id);
 
    // monoplex causes data rehash, invalidating the frangipani
    multiplex($frangipani, $multiplexorId);
 
    return $frangipani->widgets();
}

This is useful only when the obvious, simple solution to a problem had a killing flaw that is not obvious. This is a warning sign to the programmer coming after you that you have tried the obvious. Often, when leaving notes like this, and explaining why I did something the hard way, I realize that the easy way would have worked after all. At which point I fix my code and delete the comment. But at least in that case the comment did something useful.

4

An Exchange with HackerOne

In a recent episode I rambled about a system that pays good guys for finding and reporting security holes in the software we rely on every day. Fired up with enthusiasm for the cause, I sent this message to HackerOne:

I appreciate what you are doing here, and would love if there were a tip jar where I could contribute to the rewards you give out for making the world a better place. Like Zaphod, I’m just a guy, you know? But I’d happily pitch a little bit each month to promote what you do here, and to support the people who actually make the Internet less unsecure.

I debated “insecure” versus “unsecure”, and went with “un” for reasons I don’t exactly recall. Beer may have been a factor.

I got a very nice letter back.

Thank you so much for reaching out to us with this feedback on what we are doing. We appreciate you taking the time to reach out to speak with us about what you think of the program and how you would like to participate it make HackerOne a success.

You are correct about us not having a tip jar, however, our community can support us by word of mouth let others know what we do and what our goal is and if you are a hacker or know any white hat hackers we encourage you all to use our platform and help us with making the internet safer.

We really do appreciate you reaching out and I am going to share your message with the rest of the company.

Best,
Shay | HackerOne Support

The missing word and tough-to-parse sentence make me think that this was a hand-typed response. I am happy to contribute to their word-of-mouth buzz. I do not fit the profile of the geek HackerOne is looking for, and I suspect no one who will ever read these words is pondering the question “How can I break things and still be a good guy?” But if that’s you, head to HackerOne.

On the other hand, If you own a commercial Web site and want to get a major security audit, consider posting a bounty at HackerOne. You’ll get some really skilled people trying to break in, only in this case they won’t rob you blind if they get in.

3

The First and Last Mile, and Net Neutrality

The hardest part about installing public transportation in a city not built for it is the first and last mile. That’s the mile one has to go to reach the nearest stop, and the mile they have go on the other end to reach their destination. People just plain won’t walk a mile anymore. Older, denser cities don’t have this problem; there is a tram stop nearby no matter where you live.

If Net Neutrality is torpedoed, we will have a new last mile problem. At least in urban areas, near where you live is The Backbone — the actual internet, the information superhighway. Your ISP is an on-ramp, but they’re about to be given the right to control your access to the highway. If you live in a rural area, the last mile might be more than a mile but the concept is the same.

The ISPs are just an on-ramp, but because they control the last mile (they have wires connected to your house), they control your access. That’s why there are currently laws to prevent them from abusing that power. If net neutrality goes away, we’ll have a new first-mile problem. So much information, so close, but held hostage by the wire-owners. That first step.

Some will pay the ISP’s extortionate fees. Some will be cut off from one of the key assets that decides who gets ahead these days. The rich will get richer. To be more specific, the rich people who floated this whole idea will get richer, and they don’t give a crap about anyone else. It’s not that they want the poor to remain poor, that would be evil. They simply don’t care what happens to those people.

Already here in Silicon Valley there is a company promising to be a neutral ISP, no matter what the law says. They solve the last mile with a radio dish pointed at a tower (if I’m reading their propaganda correctly), but at the moment cost/performance is not close to the guys with wires connected to my house. Even so, if the guys with wires make the slightest move toward controlling my access, They should know now that I will not remain their customer for long.

3

Your Privacy, Sold (Again)

If you watched the last season of South Park, you know what can happen if your entire Internet history is made public. Riots, divorce, the collapse of civilization. But did you know that your Internet Service Provider can keep track of every Web site you visit? Forget privacy mode on your browser; that only affects what gets stored locally. It’s mostly good for letting you do credit card transactions on someone else’s computer, or at an Internet Cafe.

It does not keep a host of companies from recording every site you visit.

Up ’till now, those companies haven’t been allowed to share that information. But that’s about to change. The companies that keep that data have cashed in on the current legislation-for-sale atmosphere and have bought a rule change that will enable them to sell that data.

Our President will no doubt sign the bill, and if there’s any silver lining to all this, it’s that his own browsing history will shortly be available for purchase. If he, or other congressional leaders, had any idea what they were signing, they would have realized that they have more to lose than just about anyone else.

For instance, DNS records already made public don’t look good for the GOP. They were collected by a group who thought the Russians were trying to hack the RNC, only to find that the communication went both ways.

Anyone want to guess how much child porn is in The Donald’s browsing history?

Meanwhile, even though I don’t go to any sites that are remotely illegal, I’ll be taking measures I probably should have done long ago to protect my privacy, rather than rely on laws. To be honest, I’m not sure exactly what I’m going to do; I’m not keen on using the Tor Browser (though I’m open to volunteering some server resources to the project). I’ll be looking at VPN’s (Virtual Private Networks) to see if they offer anonymity.

I’d be happy to hear from anyone out there with knowledge in this area. In any case, I’ll report back what I learn.

2

Defensive Programming: Put the Guards Near the Gate

We can file this one under “not interesting to pretty much anyone who reads this blog,” but it’s an important concept for writing robust code. This is part of a discipline called Defensive Programming.

Let’s say you build yourself a castle in a clearing in the woods. There is one path to the front gate, and you need to guard it. “Hah!” you think, “I’ll put the guards where the path comes out of the woods, to stop shenanigans before they even get close!” You post the guards out there in a little guardhouse, secure in the knowledge that no bad guys will reach your gate.

Until someone makes a new path. Perhaps when the new path is created the path-maker will notice that there are guards on the other path and put a little guardhouse on the new path as well. But perhaps not.

In software, it’s the difference between code that says, “when all conditions are right, call function x”, and having function x test to make sure everything is OK before proceeding.

Putting the guard by the trees:

    function x(myParameter) {
        myParameter.doSomething();
    }

    thing = null;

    ... other stuff that might or might not set 'thing'

    if (thing != null) {
        x(thing);
    }

This is fine as long as everything that calls function x knows to check to make sure the parameter is not null first. It might even seem like a good idea because if ‘thing’ is not set you can save the trouble of calling the function at all. But if some other programmer comes along and doesn’t know this rule, she might not do the check.

    // elsewhere in the code...

    anotherThing = null;

    ... other stuff that might or might not set 'anotherThing'

    x(anotherThing); // blammo!

Better to move the guards close to the gate:

    function x(myParameter) {
        if (myParameter != null) {
            myParameter.doSomething();
        }
    }

Now when someone else writes code that calls function x, you can be confident that your guards will catch any trouble. That doesn’t mean you can’t ALSO put guards out by the edge of the forest, but you shouldn’t rely on them.

2

That Tingly, Geeky Feeling

My day job is building Web applications you will never see. That is by design; my apps deal with SECRET STUFF.

The first aside about failure: My first Internet application is also one you will also never see, not because of secrecy, but because it failed. We made an immersive app with a rich graphical interface that allowed people to share photos and messages with a select group of friends. The core app acted as an operating system, able to discover compatible services to provide data. It flopped. A few years later MySpace and Facebook provided crappy platforms that allowed the world to shout at each other. In retrospect my biggest mistake (among many) was assuming people valued privacy.

ANYWAY, I build Web applications. But I come from a background of developing desktop apps, and let me tell you, even now the world of Web app development is ridiculously painful. Slowly, slowly, software design principles worked out decades ago are finding their way to the Web.

Another aside about a failure: A while back I created a framework that allowed the UI (still running in a dang browser after all this time) to connect to the server with such efficiency that when anyone anywhere made a change, everyone saw it immediately. In geek terms, I created an MVC system where the central model was shared by all clients in real time. It also allowed anyone to track the entire history of every value in the system. I had a great 3D interface for that I never got to implement. The system worked so well I still get misty thinking about it. It was (still is) marketable. That project was shit-canned for reasons I could have managed better that had nothing to do with the technology.

But goddammit, I’ll fail shooting for making something great over succeeding at the mediocre, and I’ve got the track record to prove it.

I may have that chance again. I can’t be too specific (sorry for the tease), but I’m pretty excited. So this afternoon I snuck out of work early to go and… work. But fun work. Perhaps a chance to take my failures and put them together into a game-changer. I’ve come close before.

1

Standing Rock and Internet Security

At the peak of the Standing Rock protest, a small city existed where none had before. That city relied on wireless communications to let the world know what was going on, and to coordinate the more mundane day-to-day tasks of providing for thousands of people. There is strong circumstantial evidence that our own government performed shenanigans on the communications infrastructure to not only prevent information from reaching the rest of the world, but also to hack people’s email accounts and the like.

Cracked.com, an unlikely source of “real” journalism, produced a well-written article with links to huge piles of documented facts. (This was not the only compelling article they produced.) They spent time with a team of security experts on the scene, who showed the results of one attack: When all the secure wifi hotspots in the camp were attacked, rendering them unresponsive, a new, insecure hotspot suddenly appeared. When one of the security guys connected to it, his gmail account was attacked.

Notably, a plane was flying low overhead – a very common model of Cessna, but the type known to be used by our government to be fitted with just the sort of equipment to do this sort of dirty work. The Cessna was owned by law enforcement but its flight history is secret.

What does that actually mean? It means that in a vulnerable situation, where communication depends on wireless networks, federal and state law enforcement agencies have the tools to seriously mess with you.

“But I only use secure Internet connections,” you say. “HTTPS means that people between you and the site you’re talking to can’t steal your information.” Alas, that’s not quite true. What https means is that connections to your bank or Gmail can only be monitored by someone endorsed by entities your browser has been told to trust completely. On that list: The US Government, the Chinese government, other governments, and more than a hundred privately-owned corporations. Any of those, or anyone any of those authorities chooses to endorse, or anyone who manages to hack one of those hundred-plus authorities (this has happened) can convince your browser that there is no hanky-panky going on. It shouldn’t surprise you that the NSA has a huge operation to do just that.

The NSA system wasn’t used at Standing Rock (or if it was, that effort was separate from the documented attacks above), because they don’t need airplanes loaded with exotic equipment. But those airplanes do exist, and now we have evidence that state and local law enforcement, and quite possibly private corporations as well, are willing to use them.

The moral of the story is, I guess, “don’t use unsecured WiFi”. There’s pretty much nothing you can do about the NSA. It would be nice if browsers popped up an alert like “Normally this site is vouched for by Verisign, but this time the US Government is vouching for it. Do you want to continue?” But they don’t, and I haven’t found a browser plugin that adds that capability. Which is too bad.

Edit to add: While looking for someone who perhaps had made a browser plug-in to detect these attacks, I came across this paper which described a plugin that apparently no longer exists (if it was ever released). It includes a good overview of the situation, with some thoughts that hadn’t occurred to me. It also shows pages from a brochure for a simple device that was marketed in 2009 to make it very easy for people with CA authority to eavesdrop on any SSL-protected communication. Devices so cheap they were described as “disposable”.

The Chinese are Attacking!

screen-shot-2016-12-11-at-11-06-55-am
Every once in a while I check the logs of the server that hosts this blog, to see if there are any shenanigans going on. And every time I check, there ARE shenanigans. The Chinese have been slowly, patiently poking at this machine for a long, long time. The attacks will not succeed; they are trying to log in as “root”, the most powerful account on any *NIX-flavored computer, but on my server root is not allowed to log in from the outside, precisely because it is so powerful.

But the attack itself is an interesting look at the world of institutionalized hacking. It is slow, and patient, only making an attempt every thirty seconds or so. Many attack-blockers use three tries in a minute to detect monkey business; this will fly under that radar. Trying fewer than 200,000 password guesses per day limits the effectiveness of a brute-force attack, but over time (and starting with the million most common passwords), many servers will be compromised.

And in the Chinese view, they have all the time in the world. Some servers will fall to their attacks, others won’t. The ones that are compromised will likely be loaded with software that will, Manchurian-Candidate style, lie dormant until the Chinese government decides to break the Internet. And although servers like mine would provide excellent leverage, located as it is in a data center with high-speed access to the backbone, the bad guys have now discovered that home invasion provides a burgeoning opportunity as well. Consider the participation of refrigerators and thermostats in the recent attack on the Internet infrastructure on the East Coast of the United States and you begin to see the possibilities opened by a constant, patient probing of everything connected to the Internet.

I’ve been boning up on how to block the attack on my server; although in its current form the attack cannot succeed, I know I’ve been warned. The catch is I have to be very careful as I configure my safeguards — some mistakes would result in ME not being able to log in. That would be inconvenient, because if I’m unable to log in I won’t be able to fix my mistake. But like the Chinese, I can take things slowly and make sure I do it right.

1

Apple, Machine Learning, and Privacy

There’s a lot of noise about machine learning theses days, and the obviously-better deep-learning machines. You know, because it’s deep. Apple is generally considered to be disadvantaged in this tech derby. Why? Because deep learning requires masses of data from the users of the system, and Apple’s privacy policies prevent the company from harvesting that data.

I work for Apple, just so you know. But the narrative on the street comes down to this: Apple can’t compete with its rivals in the field of machine learning because it respects its users too much. For people who say Apple will shed its stand on privacy when it threatens profit for the company, here’s where I say, “Nuh-uh.” Apple proved its priority on privacy.

A second nuh-uh: ApplePay actively makes it impossible for Apple to know your purchase history. There’s good money in that information; Apple doesn’t want it. You think Google Wallet would ever do that? Don’t make me laugh. That’s why Google made it — so they could collect information about your purchasing habits and sell it. But in the world of artificial intelligence, respect for your customers is considered by pundits to be a negative.

But hold on there, Sparky! Getting back to the actual subject of this episode, my employer recently announced a massive implementation of wacky math shit that I think started at Stanford, that allows both aggregation of user data and protection of user privacy.

Apple recently lifted their kimono just a little bit to let the world know that they are players in this realm. Have been a long time. They want to you to know that while respecting user privacy is inconvenient, it’s an obstacle you can work around with enough intelligence and effort.

This is a message that is very tricky for Apple to sell. In their advertising, they sell, more than anything else, good feelings. They’re never going to say, “buy Apple because everyone else is out to exploit you,” — that makes technology scary and not the betterment of the human condition that Apple sells.

But to the tech press, and to organizations fighting for your privacy, Apple is becoming steadily more vocal. It feels a wee bit disingenuous; Apple wants those other mouths to spread the fear. But it’s a valid fear, and one that more people should be talking about.

From where I sit in my cubicle, completely removed from any strategic discussion, if you were to address Apple’s stand on privacy from a marketing standpoint, it would seem our favorite fruit-flavored gadget company is banking on one of two things: Than people will begin to put a dollar value on their privacy, or that the government will mandate stronger privacy protection and Apple will be ahead of the pack.

Ah, hahaha! The second of those is clearly ridiculous. The government long ago established itself as the enemy of privacy. But what about the first of those ideas? Will people pay an extra hundred bucks on a phone to not have their data harvested? Or will they shrug and say “If my phone doesn’t harvest that information, something else will.”

Honestly, I don’t think it’s likely that Apple will ever make a lot of money by standing up for privacy. It may even be a losing proposition, as HomeKit and ApplePay are slowed in their adaptation because they are encumbered by onerous privacy protection requirements. Maybe I’m wrong; maybe Apple is already making piles of cash as the Guardians of Privacy. But I suspect not.

So why does Apple do it? I don’t know. I’m not part of those conversations. But I do know this: If you were to ask CEO Tim Cook that question, he’d look at you like you’d grown a second head and say, “Because it’s the right thing to do.” Maybe I’m being a homer here, but I really believe Tim when he says stuff like that. Tim has told the shareholders to back off more than once, in defense of doing the right thing.

And as long as Tim is in charge of this company, “Because it’s the right thing to do” will float for me. So as long as Tim’s in charge, I know Apple will continue to respect the privacy of its customers. Maybe to you that’s not such a big deal, but it is to me. I won’t work for anyone I don’t respect.

Email Security 101: A Lesson Yet Unlearned

So it looks like the Russians are doing their best to help proudly racist Trump, by stealing (and perhaps altering) emails passed between members of the Democratic National Committee. It seems like the Democratic party preferred the candidate who was actually part of the party over a guy hitching his wagon to the Democrats to use that political machine as long as it was convenient to him.

But that’s not the point of this episode.

The point is this: Had the Democrats taken the time to adopt email encryption, this would not have happened. When the state department emails were hacked, the same criticism applies.

It is possible to:

  1. Render email unreadable by anyone but the intended recipient
  2. Make alteration of emails provably false

But nobody does it! Not even people protecting state secrets. I used to wonder what email breach was going to be the one that made people take email security seriously. I’m starting to think, now, that there is no breach bad enough. Even the people who try to secure email focus on the servers, when it’s the messages that can be easily hardened.

There is no privacy in email. There is no security in email. But there could be. Google could be the white hat in this scenario, but they don’t want widespread email encryption because they make money reading your email.

Currently only the bad guys encrypt their emails, because the good guys seem to be too fucking stupid.

1,000,003 Words!

Screen Shot 2016-02-24 at 2.23.02 PM
It has happened. Muddled Ramblings and Half-Baked Ideas has rolled over the odometer and has blasted well beyond the 1,000,003-word line. I decided to celebrate by taking the day off work to throw out a bit of a redesign here; the old code simply did not support some of the cool new WordPress features I’ve been wanting to leverage. A ground-up rebuild is long overdue.

Even when you start with a fairly clean off-the-shelf theme, however, a great deal of fiddling and tweaking ensues. Some of the old widgets, like the colorful tag cloud and the sweet-o-meter, seem to be awol right now, and I’m not sure about the typography for reading my longer-winded treatises.

Also missing, and a little more difficult to bring back, is the poetry feed that was playing in the header. I’d like to bring it back, but at this moment I’m not sure where to put it.

What do you think? Too dark? Please leave comments here on the blog, while I work on getting the styling of the comments on the blog looking right.

Later tonight, after the celebratory single malt, I will compose the Inevitable Retrospective Episode.

3

Assembling an iomega Mac Companion Enclosure

One of the big-ass hard drives we use for backup has started to make scary noises. Not the kind of sounds you want to hear from a drive that holds important data for our family and for a few of friends around the country as well. It was time to start looking for a replacement drive. One thing I wanted to do was have a clear upgrade: with the new setup I will not have to fear the catastrophic consequences of a single drive failing.

A note on levels of catastrophe: some might think that losing backup data is an inconvenience. In the same way you could think that losing the co-piolot of an airplane is an inconvenience. But with the backup compromised, risk of disaster has gone up exponentially. At Muddled Ramblings and Half-baked Ideas we take that shit seriously as we skulk in our secret bunker, buried deep beneath a trailer park next to a sprawling cemetery, ready for the Zombie Apocalypse to begin.

There are fancy enclosures that hold several drive units and use a variety of schemes that fall under the general acronym RAID to protect data from the failure of a single drive. Most of those enclosures have loud fans, and all of them cost a lot of money. Where does a cheap bastard go when he wants RAID 5, quiet and cheap? He buys a bunch of inexpensive but high-quality disks, puts them in inexpensive but high-quality quiet enclosures, and uses SoftRaid to turn them into a single virtual disk with reasonable protection from disaster.

After a little research, I found the right drives (Seagate bulletproof datacenter-rated blah blah blah) and the right enclosure: the iomega Mac Companion. What is great about this enclosure is that it has TWO firewire connectors, so you can daisy-chain them and connect many drives to a single firewire port on the host computer. Music to cheap-bastard ears, and not found on other enclosures at any price. Plus, you can buy them cheap on eBay in any quantity you might want, while supplies last.

There’s a catch, of course: iomega is defunct, and never officially sold this enclosure without a drive already installed. The packaging looks as though they might have been planning to sell empty enclosures, but the documentation (and even some of the text on the box) is clearly written with the assumption that the drive is already in there and everything is assembled.

So, you have packaging clearly designed to contain an empty, partially-disassembled hard drive enclosure, and instructions clearly for a pre-assembled unit. Weird. Perhaps some last, desperate attempt to sell an inventory of enclosures the company could no longer afford to fill. The only intern left to handle the packaging had no idea what to do about the instructions. We’ll never know the whole story.

But there’s a glut of quite capable hard drive enclosures out there now, and I bought some of them. As for assembly, there are no instructions. Not in the box, not online. You’re on your own, buddy. Until now! By my third enclosure, assembly was actually pretty easy. As a public service to anyone else who might have jumped on this deal, here are step-by-step instructions. You don’t have to thank me, it’s what I do.

Step 0: Survey the stuff.
When you open the box you will see parts in two groups: the top and the bottom. The bottom section includes the plastic base, the metal housing, and the circuit board, which is attached to the bottom of the aluminum inner shell. The top section has an aluminum inner shell top and the plastic lid for the enclosure.

Let’s take a moment to visualize the final product. A hard drive mechanism, inside a protective metal inner shell, inside a sturdy enclosure with lights on the front. With that in mind, we will be building from the middle out. (Yes, I thought of Silicon Valley when I wrote that.)

Step 1: Start by disassembling the bottom parts even further. Carefully pop the plastic base out of the outer metal housing, then slip the circuit board with inner shell off the plastic base. This is the step that took me three tries to learn. After this, everything is actually pretty obvious.

Step 2: Set the hard drive onto the white shield over the circuit board and slide it forward onto its connector.

Step 3: Slide the top inner shell over the drive unit with the little pigtail cable sticking out the slot in the side. At this point, you have something that looks like this:

IMG_0420

Step 4: If you look at the picture, you will see a screw holding the drive in place. The enclosure does not include the screws, but they are a standard size. I’m not sure what size, because I had some in my hardware collection, but you can figure that part out. In fact, in the first drive I assembled, I didn’t use any screws at all. I resolve to not use that drive as a maraca, and all will be well. But if I had it to do all over again, I’d screw those bad boys down.

Step 5: Slip your well-shielded hard drive assembly back onto the plastic base. Fiddle with things until the connectors line up with the holes in the base.

Step 6: The circuit board on the end of that pigtail cable hanging out the side actually has four LED’s on it. The tiny circuit board fits into a slot in the plastic base. Note that there is a wee indentation in the board at one end; that part goes DOWN, where it seats neatly on a plastic fin:

IMG_0415

Step 7: Now it’s time to put the outer metal housing on. There’s an odd plastic bit you set aside earlier with four little shafts sticking out. Those go into the holes in the front of the housing, and as you put the housing down over the plastic base the odd plastic bit will slide into the holder directly in front of the circuit board from step 6.

IMG_0422

Step 8: At this point, everything is connected and should be functional. Before passing the following Point of Maybe-No Return, I plugged in each unit and made sure it spun up happily.

Step 9: Snap on the lid. You’re finished! Woo!

I have no idea how to remove the lid again; and hopefully I’ll never have to learn. Now I have a lot of room for data. Setting up my poor-man’s RAID will likely have to wait until next weekend, and hopefully will be simple enough that I don’t need to write a how-to. In the meantime, I hope this is helpful to those who find themselves with a question mark hovering over their heads as they stare at the parts they have just received.

10

Could Someone Do a Quick Test for Me?

I wonder if any Microsoft IE/Edge browser users out there would mind taking five seconds to pop over to http://knives-the-novel.net and check the little red thermometer-thingie on the left. It should do an animation to show partial progress toward a goal. I’ll be trying to test it myself, but we don’t call our Windows machine “The Anger Box” for nothing.

Thanks!

It should end up looking like this.

It should end up looking like this.


A little more background for the curious:

It’s easy to put simple animations directly into SVG images, to scoot things around and whatnot. The embedded-in-SVG style of animation is based on SMIL. Microsoft has taken the position “we’re not going to support that, because there are better ways to do animations, like with CSS.” They’re right, for certain definitions of “better”, but to take full advantage of the better aspects of CSS animation one must jump through some hoops — especially if you want to adjust the animation at run-time. So, if “better” means “simpler”, then not so much.

But now my plugin’s hoops are through-jumped, and to my eye, animations are smoother in all browsers (hardware acceleration is more consistently available to CSS-based animations), so it’s a win all-round. Safari still leaves annoying trails in some circumstances, but overall things look pretty sweet in the mainstream browsers. Although, as mentioned above, to date I have no idea how it looks on Microsoft’s IE/Edge browsers. Any help in that regard would be welcome.

wp-cli, Where have you been all my life?

WordPress updates can be pretty insecure. FTP was invented back before there was an Internet, and when when no one thought that bad people might be on the same network you’re using (why even have a password if you let everyone see it?). Ah, for those naïve and simple times!

Yet even today most of the Web-site-in-a-box products you can get to run on your GoDaddy account use FTP. I control my own server, and you can bet your boots that FTP is turned right the hell off.

It can be a hassle setting WordPress up to allow its update features to work in a very secure fashion, however. I was wrangling rsa certificates when I ran across another solution: rather than push a button on a web page to run an update, log into the server and run a command there. Simple, effective, secure, without file permission fiddling and authorized_keys files.

wp-cli does way more than updates, too. It is a tool I’ve been pining for for a long time, without even knowing it. Want to install a plugin? wp plugin install "xyz" and you’re done. Back up the ol’ database? They have you covered. Welcome to my tool belt, wp-cli!

If you’re not afraid to type three commands to update your site, rather than trying to maintain a hole in your security in such a way that only you can use it, then this is a great option for you. Check it out at wp-cli.org.

An Internet Security Vulnerability that had Never Occurred to Me

Luckily for my productivity this afternoon, the Facebook page-loading feature was not working for me. I’d get two or three articles and that was it. But when it comes to wasting time, I am relentless. I decided to do a little digging and figure out why the content loader was failing. Since I spend a few hours every day debugging Web applications, I figured I could get to the bottom of things pretty quickly.

First thing to do: check the console in the debugger tools to see what sort of messages are popping up. I opened up the console, but rather than lines of informative output, I saw this:

Stop!

This is a browser feature intended for developers. If someone told you to copy-paste something here to enable a Facebook feature or “hack” someone’s account, it is a scam and will give them access to your Facebook account.

See https://www.facebook.com/selfxss for more information.

It is quite possible that most major social media sites have a warning like this, and all of them should. A huge percentage of successful “hacks” into people’s systems are more about social engineering than about actual code, and this is no exception. The console is, as the message above states, for people who know what they are doing. It allows developers to fiddle with the site they are working on, and even allows them to directly load code that the browser’s security rules would normally never allow.

These tools are built right into the browsers, and with a small effort anyone can access them. It would seem that unscrupulous individuals (aka assholes) are convincing less-sophisticated users to paste in code that compromises their Facebook accounts, perhaps just as they were hoping to hack someone else’s account.

I use the developer tools every day. I even use them on other people’s sites to track down errors or to see how they did something. Yet it never occurred to me that I could send out an important-sounding email and get people to drop their pants by using features built right into their browsers.

It’s just that sort of blindness that leads to new exploits showing up all the time, and the only cure for the blindness is to have lots of people look at features from lots of different perspectives. Once upon a time Microsoft built all sorts of automation features into Office that turned out to be a security disaster. From a business standpoint, they were great features. But no one thought, “you know, the ability to embed code that talks to your operating system directly into a Word doc is pretty much the definition of a Trojan Horse.”

So, FIRST, if anyone asks you to paste code into the developer’s console of your browser, don’t. SECOND, if you are in charge of a site that stores people’s personal data, consider a warning similar to Facebook’s. Heck, I doubt they’d complain if you straight-up copied it, link and all. THIRD, just… be skeptical. If someone wants you to do something you don’t really understand, don’t do it, no matter how important and urgent the request sounds. In fact, the more urgent the problem sounds, the more certain you can be that you are dealing with a criminal.

3