The Hiltmon

On walkabout in life and technology

Standard Markdown

Looks like Jeff Atwood (@CodingHorror), John MacFarlane, David Greenspan of Meteor, and folks from StackExchange, Github and Reddit have put their money where their mouths are and released the first version of Standard Markdown at http://standardmarkdown.com.

I believe this will be the future of John Gruber’s (@daringfireball) Markdown.

Up until now, I have relied on Fletcher Penney’s (@multimarkdown) MultiMarkdown on the desktop for all my documents because of its consistency, ubiquity and wonderful extensions for writers (including tables and footnotes). I use rdiscount for this blog for the same reason (especially it’s speed).

I look forward to seeing Standard Markdown being integrated into these tools to remove inconsistencies, but rely too heavily on the extensions that are missing from Standard Markdown to consider a switch just yet.

I will, however, be watching the development of this very closely.

Update Sep 4th, 2014

It seems John Gruber, the creator of Markdown, was not in the loop on this:

Not cool.

Knowing this now, I’ll wait to see if and how he responds first.

Follow the author as @hiltmon on Twitter.

The Quick Code Cleanup

The quick code cleanup is a process whereby you run through some or all of the files in a software project and tidy them up. Think about it as the regular tidying of your desk (or room) and filing things away – versus the rearranging and rewiring of a full code refactor. You can get a lot more done on a tidy desk.

Quick code cleanups can and do include some minor refactoring, but they are mostly about renaming items, reformatting code and commenting on or cleaning up messy sections. No features are added or changed.

So why do quick code cleanups? Because they save tremendous time as the project progresses. And the best part is, you do not need to do much thinking or need the zone (See the Four Hour Rule). For example, I just spent the last few hours doing a quick code cleanup while watching the US Open tennis!

Here are some of the things to do in a quick code cleanup:

Fix Bad Names

Naming classes, functions and variables is hard. Knowing how they may be used or evolve is almost impossible beforehand. When you name new classes, functions or variables, you have an idea of how you think they will be used. But as the program evolves, these old names may no longer be sufficiently explanatory or correct.

In a quick code cleanup, you revisit naming after-the-fact, but close enough to remember your thinking, knowing how the elements are now being used. You will find that you have a much easier time finding and choosing better names in cleanup. It also means that, when writing new code, you can relax a bit knowing you’ll come back and rename the items you are unsure of.

It makes the code more understandable for later.

Fix Lazy Formatting

While coding, we often forget to format our code properly. Or the IDE (I’m glaring at you, Xcode) helpfully generates its own code layouts for you.

In a quick code cleanup, you reformat the code to whatever standard you prefer, add white space, and rearrange the functions in files to make more sense. For example, I like to have functions that call each other closer to each other in the file so it’s easier to see them on the same screen. At coding time, I may not have written them or know which, at cleanup time I do. I also like to separate paragraphs of code with white space and comments, which I add in cleanup.

It makes the code a lot more readable and browsable for later.

Explain Some Decisions

If you have ever been in a code review you’ll know that the most common question is “WTF were you thinking?”. We know what we were thinking when coding, and we remember that thinking for a short while. But we all forget that thinking over time as other thoughts take over.

In a quick code cleanup, you add comments where necessary to explain your thinking. Why did you design a class this way, or write something that way. Or how does this complex calculation work? What was I thinking at the time?

It makes the code a lot more maintainable for later.

Early Cruft Removal

We all create classes and functions, use them for a while, and then replace them. We do not always remember to remove unreferenced classes or comment them out from the code base. Later on, when searching for how something went badly wrong, we get confused by this extra code. Is this the function called or another? This, to me, is how cruft starts.

In a quick code cleanup, while your mind is fresh, remove all classes and functions that are not being used. If you need them again later, you can get them back from source code control. If unsure whether something is being used, use search in your IDE to see if the function or class is referenced (or just comment it out and compile – if the compile passes, it is cruft).

It makes code smaller, simpler and less confusing for later.

Basic Refactoring

Other than renaming classes and variables, a quick code cleanup also usually entails:

  • Pulling up common and duplicated code into functions, or replacing long, complex, deep if clauses with function calls
  • Adding standard file headers (if necessary)
  • Hiding public variables behind setters and getters (one or both)
  • Commenting out or deleting surplus debug statements
  • Adding missing asserts to document your assumptions

It reduces the number of potential bugs for later.

When to run a quick code cleanup?

I try to do this every few weeks on current projects, when the code is still fresh in my mind and when I have some time. This often coincides with a minor release or the few hours at the end of the week when I know I will not have enough time to enter the zone and work on a new feature.

The quick code cleanup may not seem to be a productive use of your time, but it pays off tremendously as the software grows in size and complexity. As the code-base expands, it yet remains understandable, readable, maintainable, simpler and with fewer bugs, enabling you to spend more time crafting new code and less time figuring out what the hell happened in the past and untangling a knotted mess.

You can start doing quick code cleanups anytime.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Aral on Spyware 2.0

That word is spyware.

Let me state it plainly: Google is a spyware company. Facebook is a spyware company. Any company whose products spy on you is a spyware company.

The first step in understanding and defeating something is to call it what it is.

Read Here

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Quote of the Day

In sum and once again: Amazon is not your friend. Neither is any other corporation. It and they do what they do for their own interest and are more than willing to try to make you try believe that what they do for their own benefit is in fact for yours.

Replace Amazon with any company name of your choice and this remains 100% true.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

An Xcode C++ Client-Server Development Trick

I’m working on a C++ product that has a series of client executables that need to talk to a server executable. And they all share a lot of common code.

The traditional approach to build and debug this pattern is to create a library of the common code in one project, a separate server project and another client project, then jump between windows to edit and compile where needed.

But I am often coding on my trusty 13” MacBook Air screen and it’s just too tiny to have all these Xcode windows open with their console windows visible. I even prefer this on the 27” Display where I can see documentation and other windows nearby.

It turns out that Xcode does support running multiple targets simultaneously, and you can get away without the additional library compile.

Take this spike I am working with. It has two targets, szp-server and szp-client representing the server and client components.

The common code is in the common folder. Each file in the common folder is assigned to both targets (in the File Inspector Panel) so they get caught by both project compiles.

Each target also has a scheme, so each can be run as normal.

The simple trick is that I can switch to the szp-server scheme and launch it (regular run or instruments), causing the szp-server to start and display its output in the console window. I can then leave it running while working on the szp-client.

I can select the szp-client scheme, edit, compile and run it as well. Xcode treats the second run the same as another thread. You can see its CPU and memory use, run one or the other in instruments and even switch console logs, all in the same Xcode window.

And the best part. One window, easy on the small screen and no switching windows.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

WordCounter

WordCounter by Christian Tietze (@ctietze) does one thing, and does it well:

It counts the number of words you type in registered applications and displays the total on the menu bar.

Most writers I know use several different software tools while writing, like nvAlt for notes, Byword for short pieces and Scrivener for the big things. But each of these has a separate word count (if at all). WordCounter brings them all together in one. Perfect!

Available direct at http://wordcounterapp.com.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Sonicwall Mobile Connect for OS X Mavericks

If you are running OS X 10.8 or lower, please refer to SonicWall NetExtender for OS X Mavericks, this only works for 10.9 Mavericks and above.

Step 1: Download from the App Store

It’s available here: Sonicwall Mobile Connect.

There is no Step 2.

The best part of this new edition is that this is a real OS X app and it integrates with Apple’s VPN settings.

Which means you only need to run it once, to set up and test the VPN connection. After that, you can access it from the Network System Preference or the VPN menu at any time.

Tip: If the Apple version of the VPN does not work, try again via the Sonicwall Mobile Connect app. When it asks you to accept the expired certificate, click Show Certificate, then choose Trust from the popups. Enter your password and the Apple VPN version will work from then on.

I have also been told that some older SonicWall’s may not be supported, so I cannot guarantee this will work for you.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

They Will Not Come

“If you build it, they will come”
– Field of Dreams

On Monday night, June 30, 2014, I’ll be taking the Kifu servers down and putting up a static sunset site.

I built it, they did not come. It’s time to go dark.

I know we built it right. We spent years looking at the market for non-profit management systems and found thousands and thousands of potential customers publicly expressing real needs. We met with many, many different kinds of non-profits to talk about that they needed, and with even more to talk about what we could do. We tested the idea, refined it and sought out more to talk with. We did this for three years. Only then did my partners and I decide to go ahead, set up a company and do it.

When I committed the first line of code on July 5, 2011 at 11:14PM, we knew we had a great product idea for a massive, hungry market. This was a winning idea. We even decided to bootstrap the product, give up our time, effort and potential income to make this thing.

At the time I was independent, running my own company (Noverse), designing and developing systems for Hedge Funds and iOS applications for my own clients. I decided to take the chance that Kifu would work out. So I stopped taking on new clients, I completed the iOS work I had, and I started to spend all my time developing the minimum viable product that was to be Kifu version 1.0.

It was fun.

How often does one get to design and build a leading edge product that you just know people will love, because they have already told you they need your solution. It was designer and programmer nirvana. Coding all day, dealing with some amazing creative people who provided art and words, and occasionally meeting even more potential customers and sharing the idea.

On December 9, 2011, I committed v0.7 and we brought on our first customer. They were so excited and could not wait for beta, and were happy to be our alpha testers.

Turns out this too was a very good thing. A few of our ideas did not work as well in the real world and with this customer’s help, we tuned and made the product even better.

On March 6, 2012, out came v0.9, and we went into beta. Several new customers started to migrate on. We put up the public web site, and started telling folks that the final product would be available for everyone soon.

Almost one year from the start, on July 2, 2012, I pushed out version 1.0.

I had spent an entire year of my life putting this product together and talking to folks about it.

It was ready.

I had built it.

They did not come.

For the rest of 2012, I continued to add features, go out and meet people and show them the product. Almost all expressed interest, they all saw it was better than what they had, that it met their needs and was cheaper than their current process.

But they did not come.

This was the hardest time for me personally. I had spent a year without much income building this thing in the belief that it was what all these folks had expressed was what they needed. And then it was no longer in idea, it was a real product. They all loved it when they saw the demos, and it passed all their tests with flying colors.

But when the time came for them to sign up, they did not. Their reasoning never had anything to do with their need (we filled it) or price (we were better) or quality of product (we hit their sweet spots).

It was “too hard” to migrate (even though we had run several migrations and offered to do it for free) or our company was too small or our track record was too short. Or they did not want to think about it now, or wanted to wait until year end, or “run it up the tree”.

They simply did not come.

This confused me. I did not understand why these good folks were prepared to spend more money on inferior systems that were rife with faults, workarounds and were easy to defraud. I did not understand why they were prepared to spend more to do things manually, incorrectly and frustrate their constituents. I did not understand why they loved my product, spent vast amounts of time and effort discussing and reviewing it, but would not commit to it.

Luckily for me I had Noverse, new clients, new projects and new challenges to get me out of the funk, and put a few dollars in the bank. The rest of the Kifu team were out there marketing, and I provided technical support, new features and demos.

By May 2013, we realized that this was not going anywhere. But we wanted to give it another try, a new marketing push. The product had been out for many months, it was stable and the existing customers were exceptionally happy with it.

They still did not come.

We knew by December 2013 that Kifu was over and started to prepare for the shutdown. It was the right decision to make. There was no point investing more time and effort in a product that had not yet returned any value to us.

We had all lost heart and moved on.

But we did not walk away.

I have spent the last six months making sure that our existing customer’s data is where they need it in the form they need it. And that the servers have stayed up and functional while they migrated away. That has now happened.

It’s time.

On Monday night, June 30, 2014, I will back up the servers one last time, point the DNS to the sunset site and shut it down.

I am happy and proud that I built it. I can still stand up and state truly that I made a great product. I am sad and disappointed they did not come and the product did not succeed. And there is much I have learned from the experience.

sudo shutdown now "Kifu will now go dark"

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Hiltmonism - on the Floor

At least once a month, step out of your cubicle or office and spend a day on the floor. It will make you a better software designer and developer, it will help you make better software for the folks on the floor, and it will build a better relationship with them so issues and ideas can flow.

I spent Friday on the floor of my work. As I do at least once a month. My software and their workflows are significantly better for it.

What is the floor? It’s the place where folks will be using your software. If you are writing a warehousing system, it’s the warehouse floor. An accounting system, the desks of the bookkeepers. A trading system, the trading floor. A social network, the coffee shop.

One of the biggest problems with software design and development is knowing exactly what needs to be done. We developers have tried a lot of things, and continue to find new and better ways to figure this out. From requirement specifications, to use case stories, to meetings, to prototyping, all different ways to figure out what needs to be done. We work with analysts and managers to understand the problem domain and make design decisions. We work with some of our users to discuss and test ideas.

But no matter how many meetings and documents and email conversations we have, we developers often miss what the users actually need, want and mean. Communication breaks down like the “broken telephone” game. Our interpretation of the systems and tools may help them somewhat, but just as often, they miss. And our users need to work around the tools we give them to keep going.

But if we, the designers and developers, were on the floor, we could see with our own eyes what our users actually do, and how badly or brilliantly they do it. We can see the problems they face that they cannot communicate, the things they spend more time on than they should. We can see the things they have not mentioned. We can see how our tools really help or hinder them. And we can talk with them directly about it, in context.

There is no way we can get real work done on the floor, we need time and solitude to design and develop. We need to take away from the time spend on the floor new ideas, better solutions or at worst, a clearer understanding of the problem space. And apply our talents to that.

It’s not easy to explain to a manager that you need to take a day off from programming and spend time with your users, sitting next to them as they work or riding along. For some managers, that’s violating the chain of command or “working behind their backs”. For others, they feel they are paying you to program, not to understand, that be their job. The only solution I ever found that worked was to start the conversation early, spend short amounts of time on the floor with users discussing specific topics while they observe and let them see for themselves how much better it works when you and your user put your heads together.

But I think the biggest gain I get from spending time on the floor is the relationships that get built. I get to know my users and how they think, and they get to know me. And once we know each-other, it becomes easier to communicate. I get to learn and speak their language, and they get comfortable enough to start sharing their ideas and issues. And the day you come back on the floor with a feature or change they asked for, that is a very good day for all.

As a designer and developer, I am at my peak when I understand the problem domain, and am pretty useless when not. You can learn only so much from meetings and emails, but without knowing what questions to ask, you will always miss out on the “unknown unknowns”, the things you do not know that you do not know. On the floor you will see things and hear things that you had no idea were happening, can meet the folks doing those things and discuss and understand them. That increases domain knowledge, and that makes you a better designer and developer.

So, once a month at least, spend some time on the floor. Feel the pulse, get involved in the conversations, look out for new behaviors, activities and issues and talk about them, observe and identify the flows and habits, and build a better relationship with your users.

Soon, you will no longer be that mysterious IT person, you’ll be part of the team. Their part is to do what they do, your part is to make great systems for them. Together, every one wins.

I spent Friday on my floor. I learned that my users had no idea certain features they wanted did actually exist, and showed them how to access them. I found out about several design decisions that missed what they needed (and even corrected a few). I found out about a process I had no idea we had. I improved my domain knowledge immeasurably, and look forward to spending more time with them on the floor.

This article is part of a series on Hiltmonisms, a series of catch-phrase ideas that I have been learning, developing and using for years to improve my craft and the craft of those around me.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Upgrading Octopress to Jekyll 2.0

So this happened today:

I’ve been waiting for this. Now that it has, I decided to finally upgrade this site.

It was easy. As per Updating Octopress, I just ran:

git pull octopress master

Then, to ensure all gems were up to date, I ran

bundle update

Finally, I got ready - update source, clean caches and generate the blog. Note that I chose not to update the style as I like my SASS changes.

rake update_source
rake clean
rake generate

And it failed.

One thing went wrong and it was because of a old change in Jekyll. You see, before the upgrade I was using the positively ancient Jekyll 0.12. Since 1.11, Jekyll has added excerpts, where it takes the first markdown paragraph in a post and generates that as the excerpt, which it then runs through Liquid. However, I often start a post with the blockquote tag and many of these quotes have multiple paragraphs. The result:

1
2
3
4
5
6
7
8
Hiltmon@Dauntless:HiltmonDotCom (master *) $ rake generate
## Generating Site with Jekyll
identical source/stylesheets/screen.css
Configuration file: /Users/Hiltmon/Projects/Spikes/HiltmonDotCom/_config.yml
            Source: source
       Destination: public
      Generating...
  Liquid Exception: blockquote tag was never closed in _posts/2012-01-26-where-the-light-is-better.markdown/#excerpt

The post had the closing tag, but the excerpt did not.

To correct this problem, I added the following line in my _config.yml to excerpt manually or the whole post:

excerpt_separator: "<!--more-->"

The site now generates just fine.

Once again, my utmost respect and thanks to Brandon Mathis for creating and maintaining this lovely Octopress blog wrapper on top of the excellent work by Tom Preston Werner and the team who create and maintain Jekyll.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.