Tag: Software Development

πŸ›  These Software Development Tools Will Blow Your Mind

Photo by Ben White on Unsplash

For my final post of 2019, I thought I would deal with some serious FOMO1 by adding one of my own to the legions of year-end listicles adorned by clickbait headlines. You will not believe what's at number four! Nevermore shall I lament having passed up the opportunity to proffer a subjective collection of arbitrary length for your attention. Of what engrossing subject shall this list be? Life achievements? 11 places to visit before you die? Things I have discovered when looking for other things that I have lost? Nay, it shall be tools! Tools, I say. To be specific, development tools for it is tools of software development that I use often. To be even more specific, this is a list of development tools for each of which I could write an additional list of killer features, extensions, and magical whosywotsits. I present to you a list of feature packed fancies for fruitful software fabrication. How many tools? Read on to find out2.

Visual Studio Code
code.visualstudio.com

A screenshot of the Visual Studio Code environment, showing the Extensions Marketplace on the left and a JavaScript file being edited on the right, below which is shown a terminal panel indicating code has been successfully compiled. The editor is also showing an autocomplete list of possible syntax to insert. The bottom of the screen is a status bar showing additional information about the currently opened files.

This open source, cross platform, integrated development environment (IDE) backed by Microsoft really is the best I have used so far. With its built-in terminal, text editor, and task engine, it really is an integrated environment where, if it weren't for Slack and my web browser, I would spend all of my software crafting days. In fact, if I liked the extensions that integrated Slack and web browsing into Visual Studio Code, I could use it or them too; but I don't, so I don't.

Unlike IDE's of old, Visual Studio Code – often referred to as just VS Code or Code (it's command line invocation is the delightful code the-file-I-want-to-edit.js), is implemented to avoid having opinions about the code you write. Instead, it is written to support your code dictating how you write code so that you can deftly move between projects without worrying that the settings for one team will somehow traipse all over the settings for another.

If you like vim-style editors, there's a vim emulator. If you don't like the menus, use Zen Mode or go fullscreen. Want to run tests integrated in the sidebar or the test file itself? Do that. Want to run them from a terminal or via a background task? Do that instead. I could (and probably will) write a whole new list on the best extensions to use with Visual Studio Code. It is versatile enough that I believe any developer could make it the editor they need.

Why it is great for software developers?

Either natively or via an extension, Visual Studio Code supports just about every aspect of the software development lifecycle you might encounter, on every platform that likely matters (Windows, macOS, and Linux), using any workflow that suits you. Not to mention it gets feature updates monthly and is supported by a huge community of users. It takes a little DNA from editors like Atom, Sublime, and your basic text editor, and elevates them to something, well, sublimer3.

WordPress
wordpress.org

A screenshot of a web browser showing the WordPress admin screen for choosing a theme, with several themes previewed in a grid.

When concentrating on software development tools, it is really easy for me to overlook this one – probably because it is not a software development tool, at least not from first impressions. I use WordPress for this blog; I always have. There are many alternatives out there; some more technically involved than others. I know I could use markdown in a GitHub repository; I have heard of Jekyll and Gatsby and so many other ways to generate a site; I know about Medium, but for me, WordPress wins because it has the features I need, including wide support for hosting, accessibility, themes, plugins, and autonomy from the whimsy and money-grabbing aggregation platforms like Medium.

The recent updates to the core editing experience, known as Gutenberg, have been amazing and the regular updates that are auto-applied without me raising a finger keep adding polish to an already awesome experience. I can schedule posts, manage comments, and use plugins to add syntax highlighting, footnotes, multi-factor authentication, backups, and spam filtering, to name just a few. Just as with Visual Studio Code extensions, I could write another list of plugins that I love for WordPress.

35% of the web uses WordPress, from hobby blogs to the biggest news sites online.

https://wordpress.org/

WordPress is used by over a third of the web. A third! That includes this blog, almost every site that Ann Arbor Give Camp has worked on in the past few years, and rollingstone.com! If you are considering putting together any kind of website, whether a blog, or something else, I highly recommend this freely available platform that has more versatility than Meryl Streep.

Why it is great for software developers?

As I mentioned earlier, WordPress seems entirely unrelated to software development (unless you are writing themes and plugins for WordPress4). However, I have learned that writing a blog about ones technical exploits is an absolutely amazing software development tool. I never realised how much I could learn just by trying to teach someone else. I used to think a blog was about its readers and being right; I have come to learn that a blog is merely its writer, being. The act of writing a blog is where its value lies. Writing this blog identifies gaps in my knowledge, personal biases, and more. It can shine a light on my laziness, focus the my mind on a gnarly problem, and provide a scaffold from which to hang my personal growth. There are numerous times where writing posts for this blog (including some I never published) has helped me become a better software engineer. The fact that sometimes, someone reads it and finds it useful, entertaining, or infuriating is really just a bonus.

Write a blog. Hold an opinion. It is worth it.

GitHub
github.com

A screenshot of the GitHub organization's page on GitHub. The screen shows the GitHub logo (the octocat) and information including geographical location, URL, contact email, and several tabs giving more information about the organization's repositories, packages, people, and projects. The repositories tab is selected.

For some readers, this may seem a pointless entry. Using GitHub for collaborative software development is so incredibly common that suggesting folks should use it seems a bit like suggesting folks should try breathing air5. Though there are alternatives such as GitLab, GitKracken6, or BitBucket, GitHub is almost ubiquitous. I do not recall an open source project that I have interacted with recently that was not hosted on GitHub7. With the recent changes allowing private and public repositories for personal accounts, the addition of GitHub Actions for automating all kinds of workflows – free to open source, and some great improvements to code review that have been released or are in beta, GitHub is an absolutely fantastic tool for those developing software. Add to that the integrations with other tools that I use like Visual Studio Code, Slack, and third-party issue trackers such as Jira, and GitHub shines. Many feared that its acquisition by Microsoft would doom it to failure, yet the Microsoft of today is a wonderful curator of open source goodies, and it seems that we all get to reap the benefits.

Why it is great for software developers?

Free backup of your source code, code reviews, automated workflows, and more, all on a tried and tested platform with a huge community. Not only that, but if you want, you get to collaborate, build, and present work with that community8.

πŸ€·πŸ»β€β™‚οΈ That's it…

I don't know about you, but lists are exhausting. I've only written about three things and I'm already done with everything and ready for a lie down. I do stand by this list though. I really thought about what to put on it, considering the various tools I have used, not only because I have to, but because I want to. I would choose these tools from the very start of a new project unlike some others I use that, while I like them, are specific to a technology (such as React Developer Tools), are only what I use because the circumstances call for it, or are not really that standout against alternatives that I could be using.

Of course, this is all my personal opinion drawn from my personal experience; you have absolutely no obligation to agree with me. In fact, you have every right to use anything but the things I mentioned above, remaining in your state of willful ignorance, knowing you are wrong, unwilling to accept the truth as a way of life 😈. Just kidding, these are development tools, not religions – what works for you, works for you. These work for me. Perhaps you agree and want to pat me on the back from my excellent choices, maybe you care to tell me your preferred alternatives or shout at me about mine, or perhaps you read the footnotes and really have something to say about privilege, toxicity, and portfolios – feel free to engage in the comments; let's talk πŸ€—.

And with that, I bid you well until the πŸŽ†New Year and all the productive software shenanigans that await us in 2020. πŸ™‡πŸ»β€β™‚οΈ

  1. Fear Of Missing Out – a most annoying acronym, I find; why? no idea [↩]
  2. it's three, three tools [↩]
  3. don't you roll your eyes at me [↩]
  4. PHP? Ew! [↩]
  5. you really should, it is to die for [↩]
  6. mention-worthy, if only for the pun [↩]
  7. before GitHub, it was SourceForge, before the DevShare debacle – https://en.wikipedia.org/wiki/SourceForge [↩]
  8. Side Note: I think it is perfectly fine not to have a portfolio; some of the best developers I know do not have any public source, or fancy stuff to show off. This weird obsession some folks have with portfolios feels like another toxic manifestation of privilege in the software development world, and I don't care for it. Let's share what we want (and are able) to share, and accept that if we don't, that doesn't mean we're shit developers. πŸ’™ [↩]

Octokit and the Documentation Nightmare

Before I get into the meat of this series of posts, I would like to set the scene.Β Like manyΒ organisations that perform some level ofΒ software development these days, we use GitHub. Here at CareEvolution, some developers use the web interface extensively, some use the command line, and others use the GitHub desktop client1, but most use a combination of two or more, depending on the task. This works great for developers, who have each found a comfortable workflow for getting things done, but it is not so great for those involved with DevOps, QA, or documentation where there is a need to find out user-friendly details of what the developers did. Quite often, a feature or bug fix involves several commits and while each has a comment or two, and perhaps an associated pull request (PR)Β or issue has a general description, but there is no definitive list of "this is what release X contains" that can be presented to a customer.Β Not only that but sometimes a PR or issue is resolved in an earlier release and merged forward. While we have lists of what a release is going to include, quite often there is more detail that we would like to include, and we often have additional changes as we adapt to the changing requirements of our customers. All this means that one or more people end up trawling the commits, trying to determine what the changes are. It is not a happy task.

"There is nothing more difficult to take in hand, more perilous to conduct, or more uncertain in its success, than to take the lead in the introduction of a new order of things."

Niccolo Machiavelli
The Prince (1532)

Now, I know that this could all be avoided if people documented changes more clearly, perhaps added release notes to commits, raised issues for documentation changes, or created release notes on the release when it is made. However, no matter how noble change may be, anyone who has worked in process definition for any length of time will know that changing the behaviour of people is the hardest task of all, and therefore it should be avoided unless absolutely necessary. It was with that in mind that I decided mining the existing data for information would be an easier first step than jumping straight to asking people to change.Β So, with the aim of making life a little easier, I started looking at ways to automate the trawling.

I figured that by throwing out noisy andΒ typical developer non-descriptive commits like "fixed spelling" or "updated comment", and by combining commits under the corresponding PR or issue, I could create useful summary of changes. This would not be customer-ready, but it would be ready for someone to turn into a release note without needing to trawl git history. In fact, if I included details of who committed the changes, it might even provide a feedback loop that would improve the quality of developer commit messages; developers do not like interruptions, so anyone asking for more detail on a commit they made should start to reinforce that if they wrote better commits, PRs, issues, they would get less interruptions.

Octokitty2

Octokit .NET logoAfter a dismissing using git locally to perform this task (I figured those who might need this tool would probably not want to get the repository locally) and reading up on the GitHub API a little, I cracked open LINQPad β€”my tool of choice for hackingβ€” and went looking for a Nuget package to help. It was during that search that I happily stumbled on Octokit, the official GitHub library for interacting with the GitHub API. At the time of writing, Octokit reflects the polyglot nature of GitHub users, providing variants for Ruby, .NET, and Objective C, as well as experimental versions for Python, and Go.Β I installed the Octokit Nuget package into LINQPad and started hacking (there is also a reactive version for `IObservable` fans).

PokingΒ around the various objects, and reading some documentation on GitHub (Octokit is open source), IΒ got a feel for how the library wrapped the APIs. Though, I had not yet got any code running, IΒ was making progress. Confident that this would enable me to create the tool I wanted to create, I started writing some code to gather a list of releases for a specific repositoryΒ and stumbled over my first hurdle;Β authentication. It turns out it is not quite as straight-forward as I thought (the days of username and password are quite rightly behind us3), and so, my adventure began.

And then…

This is a good place to stop for this week, I think. As the series progresses, I will beΒ piecing together the various parts of my "release note guidance" tool and hopefully, end up with a .NET library to augment Octokit with some useful history mining functionality. Next time, we will take a look at authentication with Octokit (and there will be code).

  1. OSX and Windows variants [↩]
  2. or, James Bond for kids [↩]
  3. OK, that's a lie, but I want to encourage good behaviour [↩]

Why software bugs exist and how you can help

Numbers in software development are represented by fixed size variables represented in binary. These are usually 8, 16, 32 or 64 bits (each bit representsΒ a 1 or a 0). When we develop software, we choose which of these will provide enough space for the thing we are representing.

Recently, the Gangnam Style video on YouTube surpassedΒ 2,147,483,647 views and it appeared as though the view counter broke. That number is significant because it is the upper limit of a 32-bit signed integer. It turns out that the video view countΒ was being representedΒ usingΒ a 32-bit signed integer β€” a signed value1Β can represent whole numbers in the range -2,147,483,648 through 2,147,483,647; it cannot represent any number outside that range.

Though, according to YouTube, this turned out to be an Easter egg2, the bug was there before they updated the counter to 64-bitΒ andΒ it certainly is not the first time a number has pushed the limits. For example, the use of two digits to represent a year that contributedΒ to the infamous fizzle that was Y2K.

But why? Why are there bugs at all?

Although it may seem like software bugs are there just to ruin your day, they were not intentionally put there or maliciously inserted to give you a reason to "Office Space" your device. As software engineers we have to consider a variety of constraints on the software we are developing. How much space does it need to run? How much space will there be on the deviceΒ on which it is to run? How fast does it have to be? Β How many years will the software be in use3? What other software will be running? AndΒ we have deadlines by which our work has to be completed. In fact, software engineersΒ tend to consider a whole host of things such as the requirements of theΒ software (functional, spatial, and temporal4), the specification of the system on which it is to execute, project deadlines and budgets, and the expectations of the end user.

Almost always, there has to be compromise. Even though aΒ solution might be possible that accommodates all considerations, we have to deliver software in a time frame that people will pay for and some things just take too long or cost too much. That is not to say that all software bugs are because of time and money, some exist because of mistakes and as a consequence of poor design.

What does it all mean?

Software engineers like myself do not want you to encounter bugs. We work very hard andΒ theΒ QA teams work very hard to ensure that you do not get buggy software; if we see a problem, we do what we can to address it. To find these bugs, we tryΒ to consider all the ways our software might be used and test them. Unfortunately, most bugs doΒ notΒ advertise their existence quite so obviously or politely as YouTube's view counter bug. For example, when in comes to the infinite ways any one device might be configured with different peripherals and apps installed, we just cannot test them all; the system is too complex5.

Β Good developers welcome user feedback. We need your help.

Next time you encounter a bug in the software you use, whether it is a mobile app, a website, an ATM, a desktop application, or some other device, spare a thought for the software engineers. Remember, good developers welcome user feedback. Take a moment to tell themΒ or the publishers of the software about the problem.

  • What did you type, touch, or click?
  • What else was running on your device?
  • What part of the software were you in?
  • What Internet browser orΒ operating system were you running?
  • What versions?

Be as detailed as you can. All these details and more can help a software engineer track down, reproduce and ultimately fix that bug.

There is no malice in a software bug. It was not put there specifically to ruin your day. However, without your help, it will not go away. So, reach out to the developers and tell them, they will thank you for it.

Today's featured image is based on Software Bugs byΒ Martin Maciaszek.

  1. signed means it can be positive or negative [↩]
  2. An Easter Egg is a hidden feature often added to software as an amusementΒ for users who find it. Examples include the "barrel roll" in Google or the flight simulator in Excel [↩]
  3. Underestimation of this was a big contributor to Y2K [↩]
  4. i.e. how it works, what space it needs, and how long it takes to run and for how long it has to run [↩]
  5. That's a discussion for another time [↩]

Change Requests

Much like my previous post on Meeting Etiquette, this is a topic I feel strongly about. I am sure there are good reasons that people will hate some of my suggestions and I'd love to hear them, but here are my views on change requests1 based on my personal experiences.

All work is a change

I loathe projects that differentiate new work from changes to existing work. It creates two different process flows for little gain, creating points for confusion and mistakes. If all work items, whether new features, bug fixes or enhancements to existing features are raised as change requests, the work flow is the same. Everything should be tied back to requirements, regardless of the type of work, so arguments that claim there is a difference just don't wash with me. Consider a new feature as a change from not having it to having it, after all, that's exactly what it is.

Whatever the work is that is being conducted must still be implemented, reviewed and tested against requirements. Why make it harder than it needs to be?

Specify requirements, not solutions

There are many times I've been assigned a requirement that tells me how to fix something, not what needs fixing. Let's face it, everyone has an opinion but change requests are not the place to express them (except perhaps as a suggestion in the comments somewhere). A change request should clearly state the requirements that drive the change (i.e. the things that can be used to identify when the change request has been resolved) and any other information that may help (for example, steps to reproduce a bug or some rationale behind the change required).

Be descriptive

If I see one more change request with a summary or title like "Change to menu dropdown" or "Display control update", I will be rather miffed and may hurt someone (I'm British, "miffed" is just above "peeved" on the British Standards Anger Scale2). The title of a change request is very important and should give a clear indication of what the change request actually requires. Think of it a bit like twitter; it's much nicer reading some useful information in a tweet than it is to learn that someone just had a coffee. If the title is not clear, time is wasted in going to look at the description every time someone sees that change request. Every status meeting, every discussion, click click click. Save everyone the effort and get it right first time, and if you spot a title that isn't clear enough, fix it right away.

Add value

Finally, when adding comments, additional description, attachments or anything else to a change request, make sure it adds value. Leave an trail for those who follow in your footsteps so that they can discover what changed and why. Document important discussions and decisions. If you don't, you are destined to go around in circles.

Manage releases by managing change

Target changes at releases and review new changes regularly. This way, new requests raised during that release cycle can be considered for inclusion and deferred changes can be ignored until after the release. Each time a new release is started, review all the open requests and determine if they should be rejected, deferred or included in that release. Justify and document rejections in case a duplicate is raised and make sure to link duplicate issues as they can add value to one another.

Have meaningful states

I feel that there are the following possible states for a change request in any sane process to manage them.

  1. Raised
  2. Assigned
  3. In progress
  4. Ready for review
  5. Passed review
  6. Merged to trunk
  7. Rejected
  8. Closed

These are clear, unambiguous states.

  • If something is marked as "Raised", it hasn't been assigned to any release and no work should be happening on it.
  • If it's "Assigned", it should be targetted at a release (even if it's only intended for investigation at first – it can always be removed from the release back to "Raised" or rejected and closed).
  • If someone is working on something, that something should be marked as "In progress" as this helps to track progress at a glance and can also be useful if resources become available and things need reassigning.
  • If something passes testing, close it, unless you really don't trust the test team, in which case have a "Passed test" state and then review the results before closing3.

Considering these basic states, the workflow looks something like this:

State flow diagram
State flow diagram

You could add additional states if you so desired but I feel that these cover the bases well enough and provide an easy to follow work flow.

Closed means closed

Change request management gets messy when the process allows for closed requests to be re-opened. If a closed request seems like it really is now needed, raise a new request. Don't close change requests just because they aren't being done right away; if it's a real issue, then it should remain open until it is resolved.

Not always, but mostly

The guiding principle for me when it comes to change requests is simplicity. Don't make your process more complicated than it needs to be. Make it easy to follow and hard to get wrong. While I'm yet to encounter a project that required anything different to what I've suggested, I am certain there are exceptions, so if you have any, let me know. This is often a contentious, polarising topic, so I expect someone, somewhere to emphatically insist I am wrong. I can accept that, so I look forward to finding out even better ways to manage change.

  1. I made that up [↩]
  2. You may also know them as issues, bugs, defects or some other moniker that ultimately means "a repository of things to do". [↩]
  3. Flippant remarks aside, this may be valuable if you need to perform a round of customer acceptance testing after internal testing before closing out change requests. [↩]