DEV Community: Jason McCreary

42 Git Questions Answered

Jason McCreary — Thu, 17 Oct 2019 15:07:01 +0000

What is your favorite Git command?

I am a sucker for git add -p. This adds changes in "patch mode" which is a built-in command line program. It iterates over each of my changes and asks me if I want to stage them?

This command forces me to slow down and review my changes. Too often as developers we rush this part thinking the work is done. I can't tell you how many times I've run git add . in a hurry to later realize I committed "scratch" files or debug statements.
Why do you prefer using Git from the command line?

As developers, we're already using the command line for so many other things. Why not for Git as well?

In addition, Git has a very small command set. One that is pretty easy to learn as a developer and will improve your development workflow by using it directly.
How can we use stage command?

stage is a built-in alias for add.
How can I save the changes in a branch and checkout to other branch?

So you may use git stash to temporarily store your changes or make a WIP commit. The goal is to have a clean working index.

Personally, I prefer working with WIP commits rather than stash. I find them easier to reference and potentially share.
When should I use git stash?

I like to use stash for quickly getting the "working index" clean.
How do I see how to use a Git command?

Use the --help option for any command. Example, git stash --help.
What is "git flow"?

git flow is a branching strategy using multiple "long-lived" branches which mirror the software development lifecycle. Changes are merged between these branches as work is needed.
What is "GitHub Flow"?

Basically GitHub Flow is a branded name for a master/feature branch workflow. GitHub has formalized this into a process using their toolset shown in this visual tutorial.
Which branching strategy do you prefer?

I've worked on hundreds of Git projects and I will say most reach for "git flow". Only a a handful of these projects ever needed that strategy. Often because it was versioned software.

The master/feature branching strategy is much easier to manage, especially when you're just starting out. And it's very easy to switch to "git flow" if needed.
What was the git open command you used?

It's a separate command and available as an npm package.
How can you reset a branch when there are files that were added in other branch but still appear as untracked or modified in your working branch?

This is often the result of switch branches when the "working index" is unclean.

There's no built in way to correct this with Git. I normally avoid this by ensuring my prompt has a "status" indicator and running commands like git status anytime I change a branch.

These habits give me an opportunity to catch this early so I can either stash or commit those changes working on a new branch.
How can I rename a branch ?

git branch -m current-branch-name new-branch-name
How I can use cherry-pick?

git cherry-pick [reference]. Remember this is a reapplying command, so it will change the commit SHA.
If I make a revert from a branch and (for example HEAD~3), is it possible to go back to HEAD again (like a recovery of your last updates?

In this scenario, I would immediately undo the revert commit (which is the HEAD commit) by running git reset --hard HEAD~1.
When use git pull and git fetch?

git pull will download the commits to your current branch. Remember, git pull is really the combination of the fetch and merge commands.

git fetch will retrieve the latest references from a remote.

A good analogy is with a podcast player or email client. You might retrieve the latest podcasts or emails (fetch), but you haven't actually downloaded the podcast or email attachments locally yet (pull).
Why sometimes we need use --force to push the changes of a rebase?

rebase is a command which may reapply commits which changes their SHA1 hash. If so, the local commit history will no longer align with its remote branch.

When this happens you will get a rejected push. Only when rejected should you consider using git push --force.

Doing so will overwrite the remote commit history with your local commit history. So always slow down and think about why you need to use --force.
Can you use a branch to merge multiple branches and then send this branch to master?

Absolutely. It's common under most of the Git workflows for branches to accumulate changes from multiple other branches. Ultimately these branches are "promoted" into the main branch.
Should I do a rebase from a very old branch?

Only if you have to.

Depending on your workflow, it may be possible to merge a stale branch into your main branch.

If you need to bring a branch up-to-date, I prefer rebase. It provides a cleaner history of only your changes instead of commits from other branches or merges.

However, while always possible, using rebase may be a painful process since each of your commits are reapplied. This may lead to multiple conflicts. If so, I normally --abort the rebase and use merge instead to resolve all the conflicts once.
When using rebase -i, what's the difference between squash and fixup?

Both squash and fixup combine two commits. squash pauses the rebase process and allows you to adjust their commit message. fixup automatically uses the message from the first commit.
Often when I rebase my feature branch with master, for each commit I need resolve conflicts?

Yes. Since the changes from each commit is reapplied during rebase, you have to resolve any conflicts as they happen.

This means a commit conflicts early in the process, or if you resolve it incorrectly, it's likely many of the following commits will conflict as well.

To limit this, I often use rebase -i to first condense my commit history so it is easier to work with.

If there are still conflicts across many commits, I may use merge instead.
Is necessary update my branch with master before merge it with master?

Depending on your workflow, it may be possible to merge a stale branch into your main branch.

If your workflow uses "fast-forward" only merges, then it will be necessary to update your branch before merging.
Do you recommend use GitKraken?

I am an advocate for using Git from the command line. I find this keeps me in full control of managing changes, as using commands to improve my development process.

Of course, certain visual actions like managing branches and viewing file differences will always be better in a GUI. Personally, I find viewing such things in the browser during the merge process to be enough.
Could you do an --amend of a commit when it already was pushed?

Yes. However, you would not want to amend a commit after it is merged into another branch since --amend changes the commit.
When I know I will work on something for a while, should I open a pull request for each change or a complete pull request for all the work?

You normally want to open a pull request for all the work.

However, if you are working on something for a long time. It might be beneficial to merge smaller changes along the way. Doing so will prevent dependencies on your branch or staleness.

This will depend on the type of changes you are making.
Is it good practice make a release branch before merge a branch to master?

This depends heavily on your deployment process. Creating a release branch can be beneficial to group together work from multiple branches and test them as a whole before merging them into your main branch.

Since the source branches remain separate and unmerged, you will have more flexibility in the final merge.
How to take just some commits from master? Let's say I don't want to take the last commit but do a rebase.

Assuming master is your main branch, you don't want to selectively pull commits from its history. This will cause conflicts later.

You will want to merge or rebase your branch will all the changes from master.

For pulling select commits from a branch other than your main branch, you can use git cherry-pick.
Are there some special themes that I can set up on my terminal?

I cover configuring and customizing your terminal in Getting Git.
Which option is best instead of use the command git push --force?

There really isn't an alternative to git push --force.

With that said, if you properly update your branch with merge or rebase you should not need to use git push --force.

Only when you have run commands which change your local commit history from the history you previously shared should git push --force be required.
When I select drop during git rebase -, is the code related to that commit deleted?

Yes!

To revive this code, you will need to find a state prior to the rebase from the reflog.
How can we track automatically a remote branch?

Normally branch tracking is set up automatically by Git when you checkout or create a branch.

If not, you can update this the next time you push with: git push -u remote-name branch-name.

Or you can set it explicitly with:git branch --set-upstream-to=remote-name/branch-name
Is a best practice rebase a branch before updating it?

I believe so, simply for the reason organizing or collapsing your commits with git rebase -i first gives you more context during the update process.
Is there a way to split a commit into more commits (something inverse to fixup/squash)?

You could use the exec command during the rebase -i process to attempt to modify the working index and split up changes.

You can also use git reset to undo recent commits and place their changes in the working index to then separate their changes into new commits.
Is there a way to go or see a commit that was fixed up?

Not the previous commits. You can using git show to see the changes within the new commit?
What does rebase --skip?

This tells rebase to not apply the current changes during the rebase process.
How can I remove remote branches?

You can remove a remote branch by pushing "nothing" with:
git push origin :branch-name-to-remove or using the -d option with: git push -d origin some-other-branch-2.

To remove local reference to remote branches, you can run: git remote prune origin.
What's the difference between checkout and reset?

Both of these commands can be used to undo changes. checkout is arguably more robust as it allows you to not only undo current changes, but also undo a set of changes by retrieving an older version of a file.

reset, by default, works more with changing the state of changes within the working index. As such, it really only deals with the current changes.

I prefer reset. The wording makes more sense for the action, which is often to change the state or discard current changes. I tend to reserve checkout for switching branches and the rare occasion of restoring an old version of a file.
What commands should I avoid using in normal workflow?
Anything that could be destructive to your history, for example:
- git push origin master -f (NEVER)
- git revert (on a feature branch)
- git cherry-pick (changes from master)
Under a normal workflow, I try to avoid using git merge directly as this is often built into the process through pull requests.
If I have a branch (B) that points to other branch (A) and I have another branch (C) which needs code from (A) and (B) and master which process must follow to have (C) updated?

Interesting. This depends on a few things…

Are A and B something that can be merged into master? If so, you could merge A and B into master, and then update C with the latest changes from master.

If not, you may be able to simply merge B into C since it contains the changes from A already.

In the extreme case, you could merge A, B, and master into C. However, it's likely the order of merging would matter to avoid conflicts.
What are some of the aliases you use?
I don't alias Git commands often. Especially not core commands. I find doing so creates confusion, especially as a trainer.

With that said, I do have a few aliases for common commands or commands I use with a lot of options:
```
alias.unstage reset HEAD --
alias.append commit --amend --no-edit
alias.wip commit -m "WIP"
alias.logo log --oneline
alias.lola log --graph --oneline --decorate --all
```

What are some lesser known Git commands?

git bisect is a life-saver for finding an existing bug in the code. While I've only used it a few times, it has been impressively precise and saved hours of looking for a needle in a haystack.

git archive is another nice one for packaging up a set of changes. This can be helpful for sharing work with a third-party or mico-deployments.

git reflog is probably known, but worth mentioning as it provides a nice way to "undo" commands when things go wrong.
Can you recommend some books for learning more about Git?

Sure. I recommend reading at least the first 3 chapters of Pro Git. I have done so a few times over the years and always learn something.

Of course, I shamelessly recommend Getting Git. My video course covering the basic and advanced usage of all Git commands from the command line.
What if I have more questions?

Awesome. Send them to me on Twitter.

Building Products - Building an audience

Jason McCreary — Thu, 17 Jan 2019 16:19:27 +0000

I recently published the second video in the series Building Optionality where I share all the steps I take when building a new product from the ground up. As we discussed in the first video Optionality is literally from the ground up as I'm also building an audience.

This is a not an easy task, but a critical step. Too often developers overlook this step. However, it's important to emphasize that before you even start architecting or writing code for your product you need to do some initial marketing.

In the first article, I talked about how I planned to build a blog and start writing weekly content to cross post on Medium and community forums in an effort to build an audience.

Now admittedly I didn't do much over the holidays, but I want to stay disciplined about making these posts and videos each step of the way.

Since last time I probably spent roughly 10 hours on the project. Here's the breakdown:

3 hours setting up the blog.
6 hours drafting the first two posts.
1 hour deploying everything to the server.

Before I go through each of these steps in more detail, it's important to again point out that this isn't much time. Everything is MVP right now. And right now MVP means minimal effort.

Furthermore, I still haven't built any of the product. Although I wish I had because I mismanaged a few trades during December’s downturn. No, right now all my effort is going into building the audience. I'm not down in my office cave hacking away at this huge application for weeks followed by some big bang launch.

I'm going to continue to reiterate this because it’s one of the most important things about building products. In fact it parallels nicely with investing in general. Time is money. I don't want to spend a bunch of time building Optionality when it may not generate a return on investment because there is no market.

With that said, let's review each of the three things I did since last time.

First, I finished setting up Jigsaw. Jigsaw actually had a starter template which I was able to use. In fact, I don't know why I didn't see this the first time. Then I went back and watched the first video to verify they indeed updated the docs.

I spent a little time tweaking it, which really meant I jumped out to Google Fonts to give me some a super simple, text-based masthead. Otherwise it's using the starter template. Again minimal effort.

I did spend roughly 30 minutes adding a Read Time feature. I justified this as I felt it helped improve the reading experience. Investment articles tend to be long, so I want to encourage potential readers they can get through these posts quickly. This also acts as a measure for me to keep them similar in length.

A majority of time was spent drafting articles. I found it best to write two articles at a time as this allows me to get a week ahead. Everyone underestimates how much time goes into writing an article. You have to narrow a topic, write a draft, proofread, fact check, add images, tweak for SEO, cross post. It’s a process.

Admittedly these first two were probably a bit slower as I was finding the right tone and structure. Although my programmer brain wants to dismiss these nuances, they are critical. These kinds of details help build an audience and ultimately build trust that Optionality will be a useful product.

Finally, I spent about an hour deploying the site. For right now I'm piggybacking some space on one of my existing web servers. While I’m optimistic for the future, optionality.app currently gets little traffic. Again, minimal effort. No need to purchase hosting, spin up servers, etc. If I didn’t have server space just sitting, I likely would have looked at Netlify or Amazon S3 before setting up my own server.

On a similar technical note, sometimes as developers we also get caught up in the tools and services. This can be a pretty nasty time drain. Never underestimate the power of a command like rsync. It's been around since the early days of UNIX and it still crushes the use case of synchronizing remote files.

That's pretty much it this time. Soon I plan to start working on a fuller landing page with a newsletter sign-up. But as outlined in the first video, I need to get a bit closer to my goals before moving on to the next step.

Want more? Subscribe to the video series on YouTube and send me your question or feedback on Twitter.

"Audience" cover photo by Zemlinki! made available under CC BY 2.0.

Jekyll to Jigsaw

Jason McCreary — Tue, 08 Jan 2019 13:57:19 +0000

All these year in review and New Year's resolutions got me motivated. I decided use it to complete one of my own goals for the year - redesign blog. This was more or less an impromptu hackathon, which I time boxed to 4 hours to ensure I didn’t go down the rabbit hole of intricately redesigning everything.

This would be a simple facelift to modernize the template with a focus on copy, as well as a conversion of the static site generator. I decided to refactor my blog to Jigsaw. So this serves as not only my first article to christen the conversion, but also a review of the process.

Why JigSaw

My blog has been around for over a decade. I can't tell you how many times it's been converted. It originally started as static HTML, then WordPress, then Jekyll, then GitHub Pages, then Ghost, then back to Jekyll. And now, of course, Jigsaw.

Historically I used this as an opportunity to try new tech stacks. Nowadays, this is rather impractical for a few reasons.

A blog doesn't really push technical boundaries. So while it may serve as an introduction, it's not going to substantiate its use for other things.
My time is better spent elsewhere. If it's not a good learning opportunity, just go with something familiar. Jigsaw has a PHP core and leverages Laravel Blade templates engine. It also included a starter template developed with TailwindCSS and a little Vue.js.
Both of these combined bring me to my final reason of convenience. Writing blog post is hard enough already, I don't want anything to make it harder. While Jigsaw allows me to use Blade, I can continue to use Markdown.

In the end, for me, Jigsaw balanced my time by being convenient to work with (PHP + Blade + Markdown) while still giving me some light learning opportunities (TailwindCSS + Vue.js).

Converting front matter

Although front matter is pretty straightforward, I created a lot custom keys over the years while transitioning between all the static generators. So I wrote a quick script to condense these down (and reformat) to the minimal amount of: title, description, date, categories, and a few SEO keys.

Here's a Gist of the conversion script I wrote.

Rewriting URLs

Another motivation for this redesign was to finally switch to jasonmccreary.me. I purchased this domain a while back, but had not made it primary. Since I was going to change the link structure for each of my posts anyway, I took the opportunity to do both.

The key thing was ensuring my URLs redirected so I didn't lose my search engine rankings. I made sure to switch the proper settings in Google Search Console and Google Analytics, as well as generating 301 redirects for each post. There was also some tweaks to the Jigsaw config and template to ensure generated URLs consistently included the trailing slash.

Here's a gist of these scripts to convert the Jekyll posts dated filenames to the dasherized Jigsaw post filenames and generate the 301 redirects.

Tweaking categories

For the most part Jigsaw was a straight conversion. The only thing that took a minute was configuring the categories. The documentation was a bit light on how these are set up (possible open source contribution…). Again since I was familiar with PHP and Blade, it wasn't too hard to dig around the code and figure it out.

Initially, it wasn't automatically generating the category pages (or collections). Ultimately, there is an source/_categories folder within the start template where I needed to create markdown files for each of my categories.

That wasn't quite it though. The categories closure in config.php also needed some tweaks. Especially since my category names were titles and contained spaces. I had two options, I could add code to generate the lowercase, dasherized URLs in the template or I could do so at build time.

Inline with my goal to keep the writing experience easy, I preferred to generate these properly at build time. So I changed the config to lowercase and dasherize the categories names from the front matter and properly group the posts. Here's the specific code as well as a Gist of the complete config.php.

'posts' => function ($page, $allPosts) {
    return $allPosts->filter(function ($post) use ($page) {
        $category = str_replace('-', ' ', title_case($page->getFilename()));
        return $post->categories ? in_array($category, $post->categories, true) : false;
    });
}

Adding Read Time

Jigsaw also has fancy helper methods. This is pretty nice as it was a pain to customize such things and Jekyll - often requiring overriding or monkey patching in Ruby. With Jigsaw I simply add a closure in config.php and can reference it through the $page object just like I do the front matter.

This made it super easy to create something I wanted to add to my articles for a while - Read Time. It's a nice little UX hack to see an estimate of the time it will take you to read an article. I derived the formula from some of these calculations. Here's the specific code and also in the Gist of the complete config.php. I simply call $post->readTime() within my templates.

'readTime' => function($page) {
    return intval(round(str_word_count(strip_tags($page->getContent())) / 200));
}

All in all it took about 4 hours for the conversion. 2 hours were massaging the front matter, and another hour was battling the category configuration. So, in fairness, it really only took about an hour to set up Jigsaw using the starter template and begin customizing.

I plan to revisit the design, especially after reading Refactoring UI and incorporate pages for my various products and services. I like doing a little bit each time I write an article. I'll write a post and spend 15 minutes making other tweaks. So well I wouldn't call it done, I will check the box for my first 2019 goal of 2019 two redesign my blog.

Have more questions about Jigsaw? Ask me here or on Twitter. I'm glad to answer and considering packaging up some of my customizations or contributing them to the starter template.

2018 Lookbehind, Lookahead 2019

Jason McCreary — Wed, 02 Jan 2019 13:29:55 +0000

Every year I make goals. Most of my goals are focused on work, but I do squeeze a few personal goals in as well. Last year I publicized my 2018 Dev Goals. So, before talking about my 2019 goals, let's lookbehind at 2018.

2018 Goals

✅ Write a book

I published the early release of BaseCode on July 13, and the full edition on September 12. That's not entirely true, the final Exit chapter was published December 3.

I had code samples, resources, and the practices in my head well before writing BaseCode. Even with all this ready, it still took longer than I expected. For me writing wasn't the hard part, it was putting it together: proofreading, formatting.

Another delay we're all the add-ons. It would've been better to have more complete for the initial release. When I released BaseCode I sold different kits. This put a lot of pressure on me to finish quickly. Not necessarily from others, but myself.

BaseCode didn't do as well financially as I expected. I still believe BaseCode fills a gap for intermediate developers. So there is an audience. But marketing is another beast. I did better this time with a newsletter and tweets. Where I missed the mark was the release. Particularly around having influencers help me reach a larger audience in a focused, timely effort. Part of this was intentional though. I know others were willing to help, but I wanted to see how much I could do on my own. Ultimately sales for these types of products just have that initial pop, but there can also be a long tail. I expect BaseCode will bring in sales over the next few years and might eventually reach it's financial goal.

❌ Learn Python

I didn't complete this one. The reason I chose Python was for data processing. My intentions were to use it for an investments analytics tool I never got around to building. Otherwise I had no need for using Python day-to-day and hence why I didn't reach this goal.

Python is something I may still learn someday, but it's going to have to come out of necessity. There's really no reason for me to force spending time learning it in the face of my other goals.

➖ Expand Shift services

I did add more shifts in 2018, I have to be honest that I didn't technically expand the services in the way I wanted. This is still in progress, but it won't make the cut for 2018 and will carryover as a partial goal to 2019.

In particular, I wanted to add a subscription to allow users to run shifts as part of their continuous integration tools. This requires subscription billing, additional Shift, web hooks, API keys, capacity. So it is something that will would have been difficult to complete entirely in 2018 regardless. It may even be something that carries on longer than 2019.

✅ Speak at five conferences

In 2018 I spoke at 13 conferences. 13! I crushed this goal. There won't be another year like this. While I enjoyed every conference, it was too much. In 2019, I will be more selective about which conferences I submit too, what topics I submit, and ultimately accept - ideally only speaking at conferences which directly relate to my products and services or a desirable location.

❌ Reach 10k Twitter followers

Just like learning Python, I failed this one pretty epically as well. In 2018 I didn't even increase my Twitter followers more than 2017. Currently I'm barely halfway to 10k with 4,800 followers.

Reaching this goal requires a constant presence and well-crafted content. Although I always try to do the latter, the former is where I failed. This is something I will continue to focus on, but likely without the pressure of being a goal. I'll leave it as something that will hopefully happen organically.

2019 Goals

Redesign Blog

It's been several years since I've redesigned my blog. It's looking pretty outdated. This has led me to posting content on other sites like Dev.to and Medium instead of first posting here. I also plan to switch the domain to jasonmccreary.me which I picked up during a Black Friday sale.

Admittedly, this is a pretty easy goal. But it's good to start with some quick wins to get the momentum going for the year. I've found when I try to start the year with a large goal, I spend all my effort on it.

Less talks, more workshops

As I mentioned before, I plan to speak at conferences less. But speaking is something I still enjoy and want to continue. I think I'm good at spotting gaps in knowledge. It's usually not the latest fancy code or trends, but often more fundamental topics which need attention. These get overlooked, but in reality are the things we use every day and will carry us farther.

In 2017 I ran a few online workshops. Most were free, some were paid. I plan to hold a few in 2019.

Contribute to open source projects

Although I primarily contribute to the community through education, I want to contribute through code as well in 2019. The obvious candidate is to contribute more to Laravel. I have a few areas of the framework I'd like to give some attention. So I plan to learn more about the current code and see where I might be able to make a few contributes.

Improve frontend technologies

I've been a firm believer in separation of frontend and backend - particularly through APIs. I think this is and established trend and one that will continue. In 2019, I plan to go "API first" on any new project and potentially refactor some existing projects as well. This doesn't not necessarily mean single page app, but I have an opportunity to learn more technologies such as Vue, React, etc.

Build Optionality

The underlying intention of learning Python was to build an investment analytics tool. That tool has pivoted into Optionality. Building Optionality has been an intentionally slow, nuanced MVP process. However, this is a tool I plan to use personally. While I plan to honor the MVP approach and share my progress, it is something I will nonetheless build. If nothing else, to scratch my own itch. Just like a quick win, I believe you need a pet project as well.

Building Products - Starting from Square 0

Jason McCreary — Tue, 18 Dec 2018 15:15:34 +0000

Lately I've been preparing build a new SaaS product called Optionality. I want to journal this process to not just talk about the code, but also the product decisions and marketing involved in building a product.

So in this first post, I want to start at the very beginning. It's important because I rarely start with writing code. As developers, when we think of an idea we get lost in the technical details. We start pre-architecting, scaling out servers, and picking the latest tech stack to build it all.

While this is, of course, fun to think about, you can’t jump right into writing code. Too often people, not just developers, but people in general, teams, companies jump straight into building. This is a mistake.

The reality is all you have is an idea. It's really nothing. At best a few ions isolated in your brain. You have to bring the idea into the world bit by bit, proving and shaping along the way.

For example, with Getting Git, I led conference training before I recorded the video course. If I hadn’t given this at multiple conferences to full audiences, I wouldn’t have made the course. In fact, I originally planned to record a second course, but am waiting based on the response from the first before continuing with the idea.

With my book, BaseCode, I spoke at conferences, but also did a series of tweets to narrow down the topics. These tweets were a way to prove the idea and, relatively speaking, got a large number of likes and retweets.

Form there I created a mailing list. I think it was Justin Jackson that said if you don’t get 500 subscribers you probably don't have a good idea. Others like Nathan Barry and Adam Wathan constantly talk about the importance of a landing page to build your audience. This was key for BaseCode and definitely led to a more successful product than Getting Git.

Now this new SaaS will be even more challenging because it’s a different industry. For almost as long as I’ve been programming, I’ve been investing in the stock market. In the past few years, I’ve advanced into options trading. What I’ve noticed is a lack of tools around portfolio tracking and analysis.

Brokers offer this at a very basic level, but their tools focus more on trading. As a member of a few investment communities it seems most people use some kind of spreadsheet - which is a terrible, manual experience.

So I identified this gap. But again, this isn’t proof if I build it they will come. I’ve really only proven a need. To that point, the best ideas start by filling a personal need. If it’s not something I would use, it’s unlikely others will use it. You have to be willing to eat your own dog food. If not, your heart won’t be into building it and you're more likely to give up.

Now, before I run to my office cave to build this, I want to prove the market more. In order to do that, I need to grow my audience. I created a separate Twitter handle. Because of the cross over, I immediately got about 100 followers. These were developers who also share my passion for investing. However, I need to grow my true investor audience.

I started by writing weekly threaded tweets. Unfortunately it’s not growing my followers because, well, this is a new account and no one knows who the hell I am. My new plan is to take these threaded tweets and add some graphs and images to turn them into articles I can publish on Optionality. I will then cross-post on Medium, within investing communities, etc.

Remember, I don't have an audience. So I'm not even at a place where I can start to validate my idea with potential users. I'm not even at Square 1, I'm at Square 0. I have to try and grow the audience first. This needs to happen before deep-diving into writing code or architecting this portfolio tracker platform. That doesn’t mean we won’t write any code. But it’s not the app code as you might think. In fact the first thing I need to code is a blog to hold these articles.

I’m going to do this with Jigsaw. It’s a static site generator. Nothing fancy, just converts markdown to HTML and places it within a site template. No reason to install some heavy software or hand-code my own blog. I always want to do the simplest thing. Everything is an MVP.

Arguably the simplest thing would be to post on Medium under one of the investment tags. But, I need to start building a search engine presence. Optimistically, when I do build this product, I want people to be directed to Optionality, not Medium. So while using Medium directly and linking back to Twitter would be simpler, there’s value in centralizing the content with little extra cost.

Another point is I could have used Jekyll or GitHub Pages. Underneath, Jekyll is Ruby and Jigsaw is PHP (with hints of Laravel). While I am familiar with Jekyll, I am more with PHP and Laravel in general.

This is an important point because far too often developers try to pair a new idea with a new technology. This adds unnecessary complexity, ultimately lowering your probability of success. Not only are you learning your idea, you’re also learning the technology.

In the end, I balance the MVP approach while being mindful each iteration keeps me on the path towards my ultimate goal. It's not necessarily for each iteration to get you there faster or completely, but it should keep you on the path.

Now before I launch this step, I want to be clear with two more things. First, my timeline. Timelines are very important. They force accountability and reinforce the MVP approach. You can't have forever to reach your goal. Second, I need to outline measurable objectives of my goal. What am I trying to do and how can I verify it's working.

For Square 0, my goal is to grow my audience. I'm going to give myself 4 weeks to do so. I plan to achieve this goal by the following measurable objectives:

Weekly blog posts cross-posted to Medium, Twitter, and investment communities.
- Sub-goal: Have post syndicated on Medium.
Increase traffic to optionality.app measured by Google Analytics referrer and content report.
Increase Twitter following to 250 people.

I will say, some of these are a stretch. But I have to start somewhere and hold myself accountable to measurement. So we'll see in 4 weeks if these goals are met and I should continue on with building my product.

Want to follow along? Be sure to subscribe to follow me on Dev.to and subscribe on YouTube for more posts and videos.

Black Friday Deals

Jason McCreary — Fri, 23 Nov 2018 14:15:18 +0000

Just a place to share and discuss the "Black Friday" specials to help us devs save a buck on good products, services, and resources. 🤑

10 practices for writing readable code

Jason McCreary — Tue, 18 Sep 2018 16:04:14 +0000

I've been writing code for 20 years. During that time I've worked with 17 teams coding different languages to build hundreds of projects. These include everything from a simple blog site, to APIs supporting 3,000 requests/second, to top selling apps.

From these experiences, combined with the books I've read, it's become apparent to me what matters most in code: readability.

On the surface, readability may seem subjective. Something which may vary between languages, codebases, and teams. But when you look underneath, there are core elements within all code which make it readable.

Many programmers are too close to the computer. If the code runs, nothing else matters. Although a common defense it removes all of the human elements from what we do.

Over the last several months I've worked to distill these elements into 10 practices for writing code with a focus on improving readability and decreasing complexity. I've written about these in detail and applied them to real-world code snippets in BaseCode.

Many will unfortunately dismiss these as too trivial. Too fundamental. But I assure you, every bit of bad code I've encountered has failed to apply these practices. And every bit of good code you find one, if not many, of these practices.

Formatting

So much energy is wasted on formatting. Tabs versus spaces. Allman versus K&R. You'll reach a point where you realize formatting is not what matters in programming. Adopt a standard format, apply it to the codebase, and automate it. Then you can refocus that energy on actually writing code.

Dead code

All those commented blocks, unused variables, and unreachable code are rot. They effectively say to the reader, "I don't care about this code". So a cycle of decay begins. Over time this dead code will kill your codebase. It's classic Broken Windows Theory. You must seek and destroy dead code. While it doesn't need to be your primary focus, always be a Boy Scout.

Nested code

The foundation of nearly all code is logic. We write code to make decisions, iterations, and calculations. This often results in branches or loops which create deeply nested blocks of code. While this may be easy to track for a computer, it can be a lot of mental overhead for a human. As such, the code appears complex and unreadable. Unravel nested code by using guard clauses, early returns, or aspects of functional programming.

Using objects

Despite the current era of Object Oriented Programming, we still have Primitive Obsession. We find this in long parameter lists, data clumps, and custom array/dictionary structures. These can be refactored into objects. Doing so not only formalizes the structure of the data, but provides a home of all that repeat logic which accompanies the primitive data.

Big Blocks

While I don't adhere to hard numbers, code blocks can reach a critical length. When you determine you have a big block of code, there's an opportunity to recognize, regroup, and refactor the code. This simple process allows you to determine the context and abstraction level of the code block so you can properly identify the responsibilities and refactor the code into a more readable and less complex block.

Naming

Sure, naming things is hard. But only because we make it hard. There's a little trick which works well with many things in programming, including naming - deferral. Don't ever get stuck naming something. Just keep coding. Name a variable a sentence if you must. Just keep coding. I guarantee by the time you complete the feature or work a better name will have presented itself.

Removing Comments

This single practice was the original game changer for me. It's what put me on the path of focusing on readability. Despite my efforts to explain, there's always at least one person who hates me for it. They have that one example where a comment was absolutely necessary. Sure, when the Hubble telescope telemetry system has to interface with a legacy adapter by return 687 for unknown readings then that may need to be communicated with a comment. But for pretty much everything else, you should challenge yourself to rewrite the code so it doesn't need a comment.

Reasonable Returns

We return the oddest values for things. Especially for boundaries cases. Values like -1, or 687, or null. In turn, a lot of code is written to handle these values. In fact, the creator of null calls it The Billion Dollar Mistake. You should aim to return a more reasonable value. Ideally something that allows the calling code to carry on even in the event of a negative path. If there are truly exceptional cases, there are better ways to communicate them than null.

Rule of Three

Think of a mathematical series of numbers. I provide you with the number 2 and ask, "What's next?" Maybe it's 3 or 4, but maybe it's 1 or 2.1. In reality you have no idea. So, I provide another number in the series 2, 4 and ask, "What's next?" Maybe it's 6 or 8 or 16. Again, despite our increased confidence we don't really know. Now I provide another number in the series 2, 4, 16 and ask, "What's next?" Now with three data points our programmer brains see the squared series and determine the next number to be 256. That's the Rule of Three.

The example demonstrates without distracting us with code that we shouldn't predetermine an abstraction or design right away. The Rule of Three counteracts our need to fight duplication by deferring until we have more data to make an informed decision. In the words of Sandi Metz, _"duplication is far cheaper than the wrong abstraction."

Symmetry

Now for the final practice and one which gives any bit of code that lasting touch of near poetic readability - symmetry. This is pulled straight from Kent Beck's Implementation Patterns which simply states:

Symmetry in code is where the same idea is expressed the same way everywhere it appears.

This is easier said than done. Symmetry embodies the creative side of writing. It's underlies many of the other practice: naming, structure, objects, patterns. It may vary language to language, codebase to codebase, and team to team. As such, you could spend the term of your natural life pursuing it. Yet, once you start applying symmetry to your code, a purer form appears and the code takes shape quickly.

These were a high-level view of the practices within _BaseCode. I encourage you check out the resources linked in this post, watch screencasts applying these practices, or read about them in full detail applied to real-world code snippets in BaseCode._

Untangling Nested Code

Jason McCreary — Mon, 16 Jul 2018 14:55:31 +0000

I don’t believe in hard rules for writing code. You hear them often. Things like methods shouldn’t be more than 15 lines. Methods should only have one return statement. Indentation must be 4 spaces. Such rules are too rigid.

In the real world code is much more fluid. Adhering to these hard rules distracts us from what really matters - readability. If my focus is strictly on the number of lines or return statements, I prevent myself from writing more readable code simply because it is a few lines "too long" or has more than one return statement.

Many of these hard rules attempt to address nested code. Nested code is hard to follow. Physically there’s more visual scanning with the eyes. Mentally, each level of nesting requires more overhead to track functionality. All of these exhaust a reader.

Nested code is mostly the result of conditionals. Since conditionals are the basis for all programming logic, we can’t very well remove them. We must recognize their effect on readers and take steps to minimize this impact.

Getting back on top

To improve readability, we want to bring the code back to the top level. By nature, loops and conditionals have a nested structure. There's no way to avoid nesting within these blocks. However, we can avoid nesting beyond this structure.

Let's take a look at a few examples of nested code and practices for improving their readability.

Empty blocks

You may not believe me, but I've seen the following code more than once:

public function handle($request, Closure $next)
{
    if (env('APP_ENV') == 'development') {
        // do nothing...
    } else {
        if ($request->getScheme() != 'https') {
            URL::forceScheme('https');
            return redirect('https://www.example.com/' . $request->getPath());
        }
    }

    return $next($request);
}

That's right, an empty if block. I've also seen the opposite - an empty else block. There is no rule that an if must be paired with an else - at least not in any of the programming languages I've used in the past 20 years. Empty blocks are dead code, remove them.

Conditional values

Nested code blocks often return a value. When these are boolean values, there's an opportunity to condense the code block and return the condition directly.

Consider the nested code within the isEmpty method of a Set class:

public function isEmpty() {
    if ($this->size === 0) {
        return true;
    } else {
        return false;
    }
}

While this method block is only 4 lines of code, it contains multiple sub-blocks. Even for such a small number of lines this is hard to read, making the code appear more complex than it really is.

By identifying the conditional return of raw boolean values we have the rare opportunity to completely remove the nested code by directly returning the condition.

public function isEmpty() {
    return $this->size === 0;
}

Given the context of this aptly named method combined with a now one line block, we decreased its perceived complexity. Although this line may appear dense, it is nonetheless more readable than the original.

Note: Condensing conditionals can work for more data types than raw booleans. For example, you can return the condition as an integer with a simple type cast. However this rapidly increases the complexity. Many programmers try to combat this by using a ternary. But a ternary condenses the code without decreasing the complexity, making the code less readable. In these cases, a guard clause is a better alternative.

Guard clauses

Nested code is often the result of logical progression. As programmers we write out each condition until we reach a level where it's safe to perform the action.

While this flow may be ideal for execution, it's not ideal for reading. For each nested level the reader has to maintain a growing mental model.

Consider the following implementation of the add method of a Set class:

public function add($item) {
    if ($item !== null) {
        if (!$this->contains($item)) {
            $this->items[] = $item;
        }
    }
}

Logically the progression: if the item is not null and if the Set does not contain the item, then add it.

The problem is not only the perceived complexity of such a simple action, but that the primary action of this code is buried at the deepest level.

Ideally the primary action of a block of code is at the top level. We can refactor the conditional to a guard clause to unravel the nested code and expose the primary action.

A guard clause simply protects our method from exceptional paths. Although they commonly appear at the top of a code block, they can appear anywhere. We can convert any nested conditional into a guard clause by applying De Morgan's Laws and relinquishing control. In code, this means we negate the conditional and introduce a return statement.

By applying this to the add method our implementation becomes:

public function add($item) {
  if ($item === null || $this->contains($item)) {
      return;
  }

  $this->items[] = $item;
}

In doing so we have not only drawn out the primary action, but emphasized the exceptional paths for our method. It is now less complex for future readers to follow. It's also easier to test as the exceptional paths are clearly drawn out.

Switching to if

A switch statement is a very verbose code structure. switch inherently has 4 keywords and 3 levels. It's a lot to read even if the contained blocks of code are only a few lines. While this is acceptable in certain cases, it's not in others.

There are a few cases where using if statements instead of a switch statement may produce more readable code.

When there are just a few case blocks the inherent structure of the switch statement produces more lines than the equivalent if statements.
When case blocks contain nested code the complexity increases and readability decreases to a critical level. Using guard clauses or adopting the practices within Big Blocks can improve the code.
When type casts or calculations are needed to coax the value into the constraints of a switch. This doesn't apply to languages (Swift, Go, etc) that support more complex case comparisons.

switch statements are best when a 1:1 ratio exists between case statements and the lines of code within their blocks. Whether these lines are assignments, return statements, or method invocations the readability remains nearly the same provided the ratio is roughly 1:1.

switch ($command) {
    case 'action':
        startRecording();
        break;
    case 'cut':
        stopRecording();
        break;
    case 'lights':
        adjustLighting();
        break;
}

Note: In such cases where switch statements are streamlined, many programmers use a map, database table, or polymorphism instead. All of which are indeed additional alternatives. Just remember every solution has trade-offs (complexity). A switch statement is often "good enough" for most code.

Complex loops

Another common form of nested code are loops. Loops by nature are complex. As programmers, we're cursed to be off by one and miss incremental logic. Again, we're humans not computers. So we're unlikely to win the battle against loops. They will always challenge us. The only way to combat this complexity is readability.

I won't get into which data structures and algorithms may help improve your code. That is much too specialized. In general though, most loops deal with accumulation or invocation. If you find your codebase contains lots of loops, see if higher order functions like filter/map/reduce can be used. While this may not improve readability for all readers, it will improve your individual skillset.

Want more tips? This practice is taken from BaseCode - a field guide containing 10 real-world practices to help you improve the code you write every day.

Removing Comments

Jason McCreary — Thu, 15 Feb 2018 13:45:26 +0000

After my post on Boyscouting I found most of the discussion focused on code comments. Specifically, that part of boyscouting was removing comments. Tips on removing comments was also one of my most popular code cleanup tweets.

Recently removing comments came up again in a code review:

// filter out contacts that have unsubscribed
$contacts = $unsubscribedFilter->filter($contacts);

// filter out duplicate contacts
$contacts = $duplicateFilter->filter($contacts);

The reviewer asked why I "removed the documentation" when I condensed the code to:

$contacts = $unsubscribedFilter->filter($contacts);
$contacts = $duplicateFilter->filter($contacts);

I'll come back to the difference between comments and documentation. For now, there is a difference and what I removed were indeed comments.

First, let me acknowledge all the team leads and enginering managers crying out:

Remove Comments?!!

Yes, I am suggesting removing comments from your code.

Surely you don't mean removing useful comments?

Well, what's a useful comment?

Let's back up and address the distiction between comments and documentation. Documentation is formatted comment blocks (e.g. DocBlock, JavaDoc, etc). Comments are everything else.

A comment should relay why, not what or how. Said another way, if there is something that can't be relayed by reading the code, then a comment might be needed.

Going back to the code review, there was nothing the comments relayed that the code did not. I can infer from the assignment and method names we are "filtering duplicate contacts". So the code comment above is not useful. In fact, I wasted time reading it.

For me, removing comments is about acheiving code that clearly communicates. One could even refactor the code to improve readability. Consider:

$contacts->filterUnsubscribed();

Comments can not only be useful, they can also be misleading. I continually come across outdated comments that have not evolved as the code has changed. I recently needed to fix the following legacy code which was prematurely ending.

foreach ($items as $item) {
    if ($item->published) {
        // we've hit the most recent item before this push, so stop looping
        exit;
    }
}

The comment says to stop looping, but the code exits. I wasted several minutes debating which to trust. Given the bug, I updated the code to follow the comment and stop looping. Regardless, this bug would have been solved without the comment. Combined with the buggy code, it did more harm than good.

That's really what it's about – doing good. Leaving something better than you found it. That's why it's called Boyscouting. If you come across a comment that you can remove, remove it. If you can't remove it, see if you can refactor the code so you can remove the comment. Future developers will thank you. Even if that future developer is you.

I eventually came across the following passage from Rob Pike regarding comments which, quite effectively, summarizes this entire post.

[comments are] a delicate matter, requiring taste and judgment. I tend to err on the side of eliminating comments, for several reasons. First, if the code is clear, and uses good type names and variable names, it should explain itself. Second, comments aren’t checked by the compiler, so there is no guarantee they’re right, especially after the code is modified. A misleading comment can be very confusion. Third, the issue of typography: comments clutter code.

Want more cleanup tips? I'm writing a "field guide" with real-world practices to help you write code that truly lasts. Sign up for early access.

Practicing YAGNI - Show me the code

Jason McCreary — Mon, 29 Jan 2018 18:08:43 +0000

After my Practicing YAGNI post, many asked to see what practicing YAGNI looks like in code.

As a quick recap - YAGNI is a principle of eXtreme Programming. YAGNI is an acronym for You Aren't Gonna Need It.

I think Ron Jeffries, one of the co-founders of eXtreme Programming, summarizes practicing YAGNI well:

Implement things when you actually need them, never when you just foresee that you need them.

Why Practicing YAGNI is hard

Despite the fun acronym and straightforward summary, programmers often succumb to over-engineering, implementing new shiny tech, or adding additional features. Even if we overcome these urges, it's still unclear what practicing YAGNI means in code. After all, we're programmers and code speaks louder than words.

Rasmus Lerdof said to me once, "Show me the code". So I'm going to spend the rest of this article working through a series of stories. By practicing YAGNI, we'll see how the code evolves naturally, not inherently. These code samples are written in PHP to honor Mr. Lerdof.

The First Story

As marketing I want to get a list of all users so I can perform analytics.
Given I access a specific URL
Then I should get a list of all users in JSON format

The first story is the most challenging. This is when our urges are the greatest. Remember, YAGNI tells us to only implement what we actually need. Or, said another way, write the simplest thing possible.

Here is what that code might look like.

<?php
$mysqli = new mysqli('localhost', 'dbuser', 'dbpass', 'dbname');

$query = 'SELECT * FROM users';
$result = $mysqli->query($query);
$users = $result->fetch_all(MYSQLI_ASSOC);

header('Content-Type: application/json');
echo json_encode(['users' => $users]);

Admittedly this code is not elegant. It'll probably get you down voted on Reddit or StackOverflow. The Pragmatic Programmer discusses writing "Good Enough Software", and that's exactly what this is. At just 7 lines of code it's undeniably simple. Any junior programmer can readily work with the code. Most importantly, it completes the story. Nothing more. Nothing less (well, technically, we could have dumped the users table in JSON format and served a static file).

The Second Story

As legal I don't want the user's password to be in the response so we don't get sued.
Given I access the URL for the user list
Then I should get a list of all users in JSON format
And it should not include their password

So what's the simplest thing we can possibly do? Well we can adjust the SQL query to only select the appropriate fields.

<?php
$mysqli = new mysqli('localhost', 'dbuser', 'dbpass', 'dbname');

$query = 'SELECT email, role FROM users';
$result = $mysqli->query($query);
$users = $result->fetch_all(MYSQLI_ASSOC);

header('Content-Type: application/json');
echo json_encode(['users' => $users]);

The Third Story

As marketing I want to filter the user list by email address so I can group user data more easily.
Given I access the URL for the user list
And I set an "email" parameter
Then I should get a list of all users in JSON format whose email address contains the "email" parameter value

Again, let's adjust the SQL query based on the email parameter.

<?php
$mysqli = new mysqli('localhost', 'dbuser', 'dbpass', 'dbname');

$query = 'SELECT email, role FROM users';
if (!empty($_GET['email'])) {
    $query .= 'WHERE email LIKE \'%' . $_GET['email'] . '%\'';
}

$result = $mysqli->query($query);
$users = $result->fetch_all(MYSQLI_ASSOC);

header('Content-Type: application/json');
echo json_encode(['users' => $users]);

Now, while this completes the story, there are a few things we should not continue to ignore.

Increased complexity. The if statement introduces a new logical branch of the code.
Rate of change. Each of the recent stories has required changing the SQL statement.
Security risk. The added code is vulnerable to SQL injections.

These reasons should guide us to refactor our code. A common misconception is YAGNI and refactoring oppose one another. I find their relationship to be more symbiotic. YAGNI keeps my code simple, which makes it easy to refactor. If my code is easy to refactor, then I may quickly rework the code at any time. This gives me confidence to continue writing simple code and perpetuate the cycle.

So, let's refactor to extract the complexity. Being more familiar with the code at this point, a Repository object is an obvious candidate. In addition, we'll also ensure the Repository mitigates our risk of SQL injection.

<?php
require 'vendor/autoload.php';

$mysqli = new mysqli('localhost', 'dbuser', 'dbpass', 'dbname');

$userRepository = new UserRepository($mysqli);
$users = $userRepository->getUsers($_GET['email']);

header('Content-Type: application/json');
echo json_encode(['users' => $users]);

The Fourth Story

As marketing I want to see a description for "role" so I can better understand the data.
Given I access the URL for the user list
And the user's role is 1 or 2
Then I should see "Member" or "VIP" (respectively) for "role"

There are multiple implementations available, two quickly come to mind. We can implement this in the SQL statement or we could implement this with code. While updating the SQL statement is arguably the simplest, it dramatically increases its complexity. For this reason, I chose to implement this with code.

<?php
require 'vendor/autoload.php';

$mysqli = new mysqli('localhost', 'dbuser', 'dbpass', 'dbname');

$userRepository = new UserRepository($mysqli);
$raw_users = $userRepository->getUsers($_GET['email']);

$users = [];
foreach ($raw_users as $user) {
    $users = [
        'email' => $user['email'],
        'role' => $user['role'] == 2 ? 'VIP' : 'Member'
    ];
}

header('Content-Type: application/json');
echo json_encode(['users' => $users]);

This code works, however just as before it introduces new code branches and business logic. It also doubles our line count. So, I'll use some of the time I saved writing this simple solution to see if there's a more straightforward option. Indeed there is, PHP has a JsonSerializable interface we can implement to return a value to json_encode().

I can introduce a simple User object which implements JsonSerializable and move the new logic there. I'll update UserRepository to return an array of User objects. The final code is the same as when I started the story, proving a successful refactor.

<?php
require 'vendor/autoload.php';

$mysqli = new mysqli('localhost', 'dbuser', 'dbpass', 'dbname');

$userRepository = new UserRepository($mysqli);
$users = $userRepository->getUsers($_GET['email']);

header('Content-Type: application/json');
echo json_encode(['users' => $users]);

The Fifth Story

As Finance I need to get the user list in XML format so we can import it into our archaic systems.
Given I access the URL for the user list
And I set my "Accept" header to "application/xml"
Then I should get a list of all users in XML format

You're getting the hang of this now, so let's just add some if statements to vary the response.

<?php
require 'vendor/autoload.php';

$mysqli = new mysqli('localhost', 'dbuser', 'dbpass', 'dbname');

$userRepository = new UserRepository($mysqli);
$users = $userRepository->getUsers($_GET['email']);

if (strpos($_SERVER['HTTP_ACCEPT'], 'application/xml') !== false) {
    header('Content-Type: application/xml');
    // output the XML...
} else {
    header('Content-Type: application/json');
    echo json_encode(['users' => $users]);
}

We could continue down this path, but we would reintroduce code branches. If you were test driving this code with TDD (another key XP principle) you might have noticed this while adding contexts to test the different code paths. So let's use this opportunity to introduce an object.

<?php
require 'vendor/autoload.php';

$mysqli = new mysqli('localhost', 'dbuser', 'dbpass', 'dbname');

$userRepository = new UserRepository($mysqli);
$users = $userRepository->getUsers($_GET['email']);

ContentNegotiator::sendResponse($user);

In this case a simple content negotiator we pass the user data to. It might even be static as it has no state and simply outputs a response.

Retro

Let's take a look at what practicing YAGNI afforded us:

Speed. We completed 5 stories quickly and easily as YAGNI kept us focused.
Simplicity. We actually decreased the size of the initial code. We introduced new objects as they were needed, improving their cohesion.
Stress-free. Finally, we achieved all this without stress. We didn't get "stuck" worrying about the architecture or scope.

Hopefully you find the same benefits from practicing YAGNI as I have.

Want more? Follow @gonedark on Twitter to get weekly coding tips, resourceful retweets, and other randomness.

Practicing YAGNI

Jason McCreary — Wed, 17 Jan 2018 16:05:48 +0000

A while back I spoke at Laracon about Practicing YAGNI. It was an honor to present in front of such a large audience at such a premiere conference. To this day, I continue to receive a lot of feedback and interest in my talk.

To that point, many have asked me to share my slides. As the slides were mostly placeholders for discussion, I felt a blog post would better summarize the talk. Nevertheless, if you want to see the slides, you can watch my talk on StreamACon.

I consider myself a searcher. On a quest to find the Holy Grail of programming practices - that single practice which instantly levels up my skills. While I know this doesn't exist, I do believe in a set of practices. Recently, I found one to be YAGNI.

YAGNI is a principle of eXtreme Programming - something I practice daily at work. YAGNI is an acronym for You Aren't Gonna Need It. It states a programmer should not add functionality until deemed necessary. In theory, this seems straightforward, but few programmers practice it.

Why practicing YAGNI is hard

Before we continue talking about YAGNI, we need to understand the problem it solves. The problem is over engineering. At some point, we started priding ourselves on complexity - obsessed with playing design pattern bingo and building ever more intricate architectures in our head.

XKCD illustrates over engineering well with "The General Problem".

This is funny because it's true. But it begs the question - why can't we just pass the salt?

What ever happened to KISS? What's wrong with an MVP? The answer is nothing. We need to find our way back to simple. YAGNI can help us get there.

How to practice YAGNI

I think Ron Jeffries, one of the co-founders of eXtreme Programming, summarizes practicing YAGNI well:

Implement things when you actually need them, never when you just foresee that you need them.

Nonetheless, the most common contention is timing. We continually write code sooner than we actually need them. This is the over-engineer in us. We confuse foreseeing with needing.

To help distinguish between the two, we can create a time horizon. Kent Beck describes this well during an interview on Full Stack Radio:

…I did a little experiment… what if I deliberately stopped trying to predict the future and limit my design horizon to six months… things went better for me… I was less over engineering. I was making progress sooner. I was less anxious… Things were cleaner, easier to understand… So what about three months? One month? I never reached a limit with that experiment…

In this way, practicing YAGNI becomes a time experiment. One where we keep decreasing our time horizon to help limit the code we write. Ideally until we reach a point where we don't write code until it's actually needed. Not just because we're thinking about it, or want to, or it relates to code we're working on. We wait until the current code requires us to implement new code in order to work.

At first, I'll admit, this will feel like laziness. It's going to seem like you're intentionally avoiding writing code. In a way, this is true. The catch is, the code you're wanting to write isn't ready to be written. By waiting, you prevent all the bad things that happen when you make assumptions.

When not to practice YAGNI

Once you realize the benefits of YAGNI, you're going to try to apply it to everything (another programmer curse). You need to remember with great power, comes great responsibility. YAGNI isn't about saying no. YAGNI is about deferring unnecessary complexity.

As such, there will be times when you should not call YAGNI. Unfortunately, this takes experience. So I will outline a few scenarios to help those getting started.

Learning something new: You should take the time when evaluating a new technology. You'll gain the time back later, and mitigate the risk of losing more time by making the wrong decision.
Current design decisions based on future needs: YAGNI shouldn't handicap or sabotage our efforts. In these scenarios, make the future-proof design decision, but only implement enough to fulfill the current need. This allows us to limit rework, without completely undermining YAGNI.
Abstracting external dependencies: External dependencies add complexity to your project. Inline with the previous examples, taking the time to abstract these dependencies will avoid rework and decrease the complexity.
Testing, Security, Scale, and Business Requirements: Sorry, but YAGNI is not a free-pass on writing tests, secure code, considering scale, or business requirements.

What YAGNI means to me

Practicing YAGNI gives me confidence. I am comfortable delaying design decisions because I will be better informed in the future. I trust my ability to pivot quickly because my code is simple, making it easy to refactor and evolve. I write less code, and let's be honest, the best code is no code.

Want more? Follow @gonedark on Twitter to get weekly coding tips, resourceful retweets, and other randomness.

2018 Dev Goals

Jason McCreary — Mon, 08 Jan 2018 13:46:03 +0000

At the beginning of each new year set goals. While I split them between personal and professional goals, I find the lines can blur. I like what I do. So, even though these are my goals as a professional developer, they are personal goals too.

Here are my goals for 2018:

Write a book
Learn Python
Expand Shift services
Speak at 5 conferences
Reach 10k Twitter followers

I’d like to go through them. Not just to explain the goals, but the motivation behind them. In doing so, they may help you set a few goals of your own.

Write a book

I never planned on writing a book. Despite writing hundreds of blog posts, dozens of magazine articles, and several talks I never thought I had enough material to fill a whole book. I love sharing my experiences. It’s the motivation for all the writing I do.

Back in November I started sharing code cleanup tips on Twitter. Each week, I’d share a tip to cleanup your code. Each week, the tweets received more retweets and more likes. Some well into the hundreds. It’s funny as the whole thing started as a bit of a challenge. I was bored in a meeting and asked developers to send a code snippet they wanted cleaned up.

Even with all these positive responses and ensuing discussion, I still never thought I had material to write a book. After all, how do you take a bunch of tweets and turn them into a book. I mean you don’t. What you can turn them into is a field guide - a short book with pragmatic practices to improve the code you write every day.

With my birthday at the end of the month, I realized that I've been programming for 20 years. It was this realization that was actually the deciding factor. In the developer world, that’s a lifetime of experiences working with dozens of development teams, developing hundreds of projects, and writing thousands of lines of code. Combining my experience with my tweets to provide backstory and motivation for writing cleaner code in the real world felt like enough. So I am writing BaseCode - a field guide to lasting code.

Learn Python

Learning a new language a year was actually suggested to me as a good routine by a TA in college.

However, development has changed. Especially web development. When I first started knowing HTML was enough. Then it was HTML, CSS, and JavaScript. Now it's so much more. You have to learn languages, frameworks, APIs, and all the tools in between.

Technically speaking, the last language I learned was Swift. That was a few years ago. So I’m overdue. This year, I chose Python. There’s no requirement for me to learn Python. At least not for my career. I chose it because it seems to have a place in data analytics.

Investing is my second passion. I’m always looking for ways to combine my two passions of programming and investing. What better way than to analyze my trading habits with a few Python scripts. Who knows, maybe I’ll end up with an algorithm that outperforms the market and I'll start an investment firm. That's pretty unlikely, but at least I know Python.

Expand Shift Services

Two years ago I created Laravel Shift. It provides automated and human services for upgrading Laravel, Lumen, and PHP projects between major versions.

Shift has been a great side project. But I’m at a critical point where it needs work to get to the next level. Otherwise, it will likely stagnate, rot, and die. An all too common tale and one that I’ve lived before with another side project.

I don’t want to see that happen to Shift. The goal this year will be to focus the core platform by cutting some of the services that don’t generate revenue and instead put that effort into expanding to new markets - either other sub communities within PHP or even other languages like JavaScript or Ruby.

Speak at 5 conferences

Over the past few years I’ve been fortunate to make the transition from a conference attendee to a conference speaker. As I mentioned before, I love sharing my experiences. Seeing an audience engage, share, and grow during one of my talks has been incredibly rewarding.

This year I hope to increase the number of conference engagements. I’m well on the way to achieving my goal as my talks have already been accepted to 3 conferences. I expect to reach this goal, so I created a sub goal - I’d like to be a keynote speaker or speak at a new conference. Maybe one that is not even tech related.

Reach 10k Twitter followers

This goal is pretty straightforward. However, the motivations are not. It’s a means to an end. That end, for me, is reach. I’m not talking about being popular. Again, it's about sharing my experiences in an effort to teach. Every teacher needs an audience.

Reaching 10,000 followers on Twitter accomplishes two things. First, it’s positive feedback that people find value in what I am sharing. Second, it allows me to reach an audience more directly. Let me elaborate on this a bit.

Unless you’re inherently famous or virally fortunate, you have to grow your audience. You have to write blog posts, speak at conferences, and make things. Then you have to share all that carefully and meticulously. You have to ask people to share your stuff. It’s an awkward, relentless push. All that might get you a few thousand followers.

Maybe at 10k followers it might be a little easier to my experiences with a large enough core audience to make an impact.

I hope these insights into my own goals help you create some of your own. Tech is constantly in motion. Keeping up is the minimum requirement. Goals are a great way to ensure you’re not just keeping up, but accelerating.