House of Black and White

The Work Journal - A Career Tool

Tue, 28 Sep 2021 00:00:00 +0000

Do you have trouble recalling what you worked on the day before?

When quarterly reviews come around, do you have trouble justifying why you should get a raise or promotion?

When you’re interviewing for a new job and are asked about bullet points on your resume, do you have trouble answering questions concretely?

If you answered “yes” to any of these questions, I have a tool that may help you - a work journal.

I know, it’s not revolutionary. In fact, I heard about the idea from somewhere else (although I cannot recall who told me or where I read about it).

A Quick Story

A long while ago, back at a previous job, I was not happy with my job. I did not feel empowered to make changes that would would result in me being happier at my job, so I started looking for a new one.

One of the first steps in the journey of finding a new job is updating your resume, so I did that. I ran into some snags while updating my resume because I had trouble remembering everything relevant I did over the past 5-6 years of employment that I could consolidate into a number of bullet points.

When I started my new job, I decided I didn’t want to have this problem anymore, so I started keeping a work journal.

What Is A Work Journal?

It’s pretty much what it sounds like: a journal where you record work-related material. Keeping a work journal allows you to retain data about your career that you can use for different purposes, such as:

Personal reflection
Getting up to speed from the previous work day
Evidence that you can bring to reviews with your manager in order to make a case for a raise and/or promotion
Consolidating work into bullet points for your resume
Allowing you to speak concretly about the work you have done

Here are some things I like to keep track of in my work journal:

What I worked on

Writing down what I worked on allows me to give specific, relevant information to my teammates at stand-up instead of giving a vague summary, or even worse, saying that I can’t remember.

This is a huge benefit of the journal. This is what gets you raises, promotions, and jobs. If you can’t speak concretely about the work you’ve done and how you’ve made an impact, it’s going to be a hard sell to whoever you’re talking to in order to get that raise / promotion / job.

Things I learned

Quirks about the codebase, new keyboard shortcuts, new tools & technologies - these are all things that my brain sometimes forgets and it’s nice to persist these things somewhere in case i forget.

Picking A Journal Medium

It’s all up to you how you want to record this stuff. You like being tactile with pencil and paper? Do it up. You want to type it into an electronic document? I would suggest checking it into version control and pushing it to a private repo.

Personally, I have been using my ReMarkable 2 to write things down, which gives me the best of both worlds. I feel like I’m writing on something physical, but the data gets persisted digitally to a non-public place.

Reviewing Your Journal

Don’t forget to review it! Depending on the reason, you can do this at different frequencies. If you’re looking at what you did yesterday, you’ll read the previous entry on a daily basis. In order to get things together for quarterly reviews or my resume, I look at each quarter of entries and synthesize them into a number of bullet points that summarize the most important work. Do what works for you.

Example

Here’s an example of some entries from my journal. Sensitive information has been redacted. Please excuse my awful handwriting.

There are a few things here. I wrote down a learning, which I typically mark with either a “Learning” like I did here, or I mark it with the letter “L” in a circle. Feel free to come up with your own legends.

My coworker told me a great idea to try when writing tests for code. Since those of us in western countries read left-to-right, if you split-screen files in your editor and put the test file on the left side of the screen and the production code file on the right side of the screen, it will flow more easily to start with a test on the left and then make it pass on the right. Very smart.

I made a remark about how my team has been getting better with mobbing with VS Code LiveShare. At first, it was frustrating and slow, but as we did it more and worked on points of friction, mobbing has become a better experience for our team.

I have a few entries around the work I was involved with. The level of detail I write about those can vary.

Conclusion

I highly recommend starting a work journal to help you out with your career. At the end of each work day, take a few minutes to write down a summary of your day. It will benefit you from the small (remembering what you did yesterday) to the large (remembering what you did two months ago).

Lessons Learned From Giving My First Tech Talk

Sat, 22 Jun 2019 00:00:00 +0000

I recently gave a talk at the Philly XP meetup on how to use your version control data to find technical debt hotspots. It was the first tech talk that I had ever given. I’d like to talk about the process I used to come up with the talk, as well as some techniques for preparing to give the presentation.

Motivation

A while back, I read several books by Adam Tornhill that had some interesting ideas about how to do behavioral analysis on your codebase. While talking about these ideas to Nick Goede, a co-organizer of Philly XP, he suggested I give a talk about it. Without having much of an idea of what I’d talk about, I said yes and committed before actually having a talk put together. I believe this is how many talks are born. :)

Desired Outcome

The whole point of a talk is to share information with people. Out of respect for anyone who would attend the talk, I wanted to make sure that the talk would be worth their time.

I thought about what information would be useful to them and would enable them to run behavioral analyses on their own codebase in order to find their highest priority tech debt. I also wanted to show them tools to be able to actually do it and not just talk about things conceptually. Finally, I wanted to give them a few tips for addressing the tech debt once it was found. There are many books on the topic, so I limited it to a few common things that I’ve seen.

Coming Up With The Talk Material

I went back through the books that I read and put notes into a text file. I also used my own experience with running the behavioral analyses on my own codebase as material. As I wrote the notes down, I tried to group them by slide. Once I had a substantial amount of material, I translated the notes directly into the slides.

I know that it’s a bad idea to have slides that are full of text, so I trimmed down each slide to either have a phrase, idea, or image, and have each slide map to some of my notes in my text file. The notes are for my own reference, in case I forget something that I wanted to mention when talking about a particular slide.

The Slides

I tried to keep my slides as minimal as possible. The vast majority of slides had either an image or a several-word phrase that was relevant to what I was currently talking about. I had several slides that had bullet points on them. Most had two or three bullet points, although a few of them had four bullet points.

I had about 70 slides and got through the talk in about 35 minutes, so I’d say I spent 30 seconds on average on each slide. I think this helped the audience feel like the talk kept moving at a decent pace since there were few instances where I was on one slide for a long time.

Rehearsal

For rehearsing the talk, I had a 4-step process:

Record
Listen
Tweak
Repeat

Record

I recorded myself giving the talk on my phone using a sound recorder app. A number of sound recorder apps are freely available for iOS and Android.

Listen

After recording the talk, I would play it back and make notes about:

Areas where I stuttered or blanked out
Things that didn’t make sense
Places in the talk where the flow wasn’t great.

Another benefit of being able to listen to my talk is that I know how long I took. This gave me an idea of how long my talk was going to be when I actually gave it.

Tweak

Based on my recording, I would add, remove, or reorder slides. I would also adjust my notes to reflect the changes in the slides. This would become the basis for the next iteration of rehearsing the talk.

Repeat

This was an iterative process. With every iteration, the talk would have more content or become more refined. I also memorized more of the talk and eventually got to the point where I didn’t really need the notes. At a certain point, it was just rehearsal and keeping things smooth.

Giving The Talk

Despite having the material down pat, I was still really nervous. I was afraid that folks would think that what I was talking about was BS and I feared having an argument with an audience member that would expose my ideas for foolishness.

I believe being nervous for giving a talk is normal. If you’re not nervous, you may not really care about the talk you’re giving.

Also, my fears were completely unfounded. Everybody was very respectful and at the questions section at the end, a lot of people had really good questions, which led to great discussion. And even though I thought that my talk was basically a rehash of a talk that Adam Tornhill gave, some folks at the meetup told me that, with some work, the talk could be a great conference talk.

The actual speaking part wasn’t too difficult for me. I’ve performed music and sang karaoke in front of people, and I’ve also moderated a reading group at work, so I have a level of comfort with addressing a group of people. I understand that other folks have trouble with this part, and that’s okay.

Just remember, your audience is here because they’re interested in what you’re there to talk about, so they’re with you. They’re not out to criticize you and tear you to shreds; they came to learn.

The piece that really helps is rehearsing. Rehearse, rehearse, rehearse. If you know your material, you’re less likely to blank out and get thrown off.

Conclusion

I highly recommend giving a talk about something you’re knoweldgeable or passionate about. You can help other folks in your community learn and grow. A full-length talk may be a little much to bite off, so maybe start off with a 5-10 minute lightning talk. After that, work your way up.

Through a great deal of the process, I dreaded giving the talk and thought it would be something I’d never want to do again once I gave it. I was totally wrong. I now feel like I want to refine the talk I already have, or work on several shorter lightning talks on other subjects.

References

Materials for my talk can be found in this GitHub repo.

Re - The One Benefit of Software Estimation

Sun, 20 Jan 2019 00:00:00 +0000

In a previous blog post of mine, I discussed the lone merit that software estimation has: making sure folks are on the same page in regard to understanding the complexity and scope of a story.

I was wondering if there was a way to achieve this without estimation. I’ve got an idea.

Using T-Shirt Sizing As An Estimation Proxy

T-shirt sizing is a coarser form of estimation. I’ve seen it used mostly for projects rather than user stories. There are typically four sizes to pick from:

Small (S)
Medium (M)
Large (L)
Extra Large (XL)

Instead of estimating with points, we can estimate by proxy using T-shirt sizes. This works the same way as estimating with story points, but at the end of it, we can throw the estimate away. We still get the same benefit of having discussions triggered by variance in the team’s estimates as we did when doing it with story points.

Shifting In Complexity Categorization

This will most likely require a shift in thinking about the levels of complexity that each T-shirt size maps to. Whether you do Fibonacci-style estimation or something else, you’ll have to re-evaluate your thinking of complexity categories.

Example

As a member of a team who uses Fibonacci-style estimation, one potential approach is to do a mapping of T-shirt sizes to point ranges, like this:

Small -> 0.5 - 2 points
Medium -> 3 - 5 points
Large -> 8 - 13 points
Extra Large -> Larger than 13 points

Let’s say the team estimates a story with these T-shirt values:

Small, Medium, Small, Small, Small

Most of the team agrees that the story is small. There may be a conversation to explain to the team member who estimated Medium as to why everyone else thinks the story is a Small. This works just like with story point estimation.

As an aside, on my team, if we agree the a story is an 8-point story or a 13-point story, that serves as a trigger to think about if the story can be broken up further, because it usually can. Something similar can happen with T-shirt sizing. Large or extra large stories can be scrutinized to see if they can be broken up into smaller stories.

Why T-shirt Sizing?

Why not just estimate how we normally do and then throw the estimation away?

That’s a valid question. I would argue that since there are less values to pick from with T-shirt sizing, there’s less probability of squabbling over whether a story is 3 points or 2 points. T-shirt sizing quickly asks, “Are we on the same page?” If so, we can move on with our lives and if not, we can figure it out.

Conclusion

For reasons mentioned in my other post, I think software estimation is pretty useless. By using T-shirt sizing as an estimation proxy, we can reduce the cruft of estimation and focus on more important things in our work.

Your team can adopt something like a Kanban approach for prioritizing & pulling in work and, if your org is really set on getting estimates from your team, you can just give every story an estimate of 1 point and not even think about it. At that point, your ‘velocity’ is just how many stories you got done per sprint, regardless of complexity.

Common Git Aliases for Making You More Productive

Sun, 08 Jul 2018 00:00:00 +0000

As of late, I’ve been more mindful to identify areas in my workflow that I can make more efficient. If you find yourself doing repetitive tasks or tasks that take a long time, you should consider if there are ways to automate those tasks or make them take less time to complete.

One wasteful area I identified recently is the git commands I use. I found myself typing commands like git status, git checkout or git checkout -b a lot. It might not seem like much, but those keystrokes add up over time, especially if lots of other developers are doing the same thing. I was aware of git aliases, so I created a few (and borrowed others from coworkers) to make myself more efficient.

Git aliases

Aliases allow you to assign a particular git command, or series of commands, to a single command that you give a name to. Here are the aliases I use:

Checking your status

The git status command lets you know where you are in the context of git.

Some colleagues of mine have turned me onto using the alias git st.

Doing a checkout

The git checkout command does a few things, which I’m not a big fan of, since it’s not intuitive to folks who are new to git. You can check out an existing branch, go to a particular commit, or revert changes that are not staged for commit.

I use the alias git cout to save some characters.

Creating a new branch

When you supply the -b flag to the git checkout command, it creates a new branch and switches you to it (e.g. git checkout -b my-new-feature). This is the 4th thing I know that git checkout does.

I use the alias git coutb to shorten this command (e.g. git coutb my-new-feature).

Amending a commit

Sometimes after making a commit, I find that there’s a file I meant to commit, but didn’t do so because I forgot to stage it. I stage the file and amend the commit with git commit --amend.

I created an alias called git amend that does a slight modification of the git commit --amend command: git commit -a --amend. This will stage all unstaged files and amend them to the latest commit.

Deleting a branch

The command to delete a branch in git is NOT straightforward at all. It is git branch -D (e.g. git branch -D branch-to-delete). I have to think about this sometimes and don’t always remember it.

I created a straightforward alias for this command: git delete (e.g. git delete branch-to-delete).

Fetching and pulling the current branch

I frequently pull my workplace’s develop branch. I also like to have any new remote branches that have been pushed so I have an idea of that’s going on. I used to do this in two seprate commands: git fetch and git pull.

I created an alias, git fpull, which does both the fetch and the pull. It aliases the two commands being passed to the command line: !git fetch && git pull.

Adding these aliases for your own use

You can run the following commands to add these aliases to your global git config:

git config --global alias.st 'status'
git config --global alias.cout 'checkout'
git config --global alias.coutb 'checkout -b'
git config --global alias.amend 'commit -a --amend'
git config --global alias.delete 'branch -D'
git config --global alias.fpull '!git fetch && git pull'

Alternatively, you can go to a git repo I created and run a bash script that will add these aliases for you. The repo can be found on my GitHub.

Conclusion

I hope you find these git aliases helpful in making you more productive. If you have any git aliases you’d like to share, feel free to leave a comment.

The One Benefit of Software Estimation

Wed, 27 Jun 2018 00:00:00 +0000

Software estimates are mostly a waste of time. Here are some observations I have made in my career that have driven me to this conclusion:

Most software development is inherently filled with unknowns and surprise complexity. This uncertainty is difficult to communicate to managers in the form of a single number.
Management has a tendency to compare points between teams as a means of performance, despite the number of differences between the teams (size, skillset, and scale of point estimation, to name a few).
Sometimes, if a project is big enough, teams are coerced into making estimations for batches of work that will be handed off to other teams. See observation #2 above regarding differences between teams. These differences immediately render the estimates meaningless.

In fact, I can only think of one benefit of estimating that may be its saving grace.

The One Benefit: Reaching A Common Understanding

There is one benefit that estimation brings. Let me present a scenario to you:

Your team is estimating one of your stories in the backlog. The team reads the story’s details and acceptance criteria. After asking questions about the story and getting answers, the team is ready to estimate. Everyone puts their fibonacci-sequence planning poker cards face-down for estimation. When the product owner says to reveal their estimates, they simultaneously flip their cards. The estimates are revealed:

2, 3, 8, 5, 5, 13

These estimates are all over the place. In my experience, when this happens, it means that not everybody is on the same page about the details of a story. If the estimates are closer together or the same, then there is more of a shared understanding of the story amongst the team.

This wide variance in estimates warrants a conversation. Everyone goes around and gives their rationale for their estimation. It’s discovered that some of the developers gave a lower esimate because they knew of some existing code in the system that would be able to be reused for this feature. The QA folks didn’t know that, and several of them estimated higher because of a bunch of test cases they’ll have to test. This was not known to the developers.

After this discussion, the team wants to re-estimate. Once again, they put their planning poker cards face-down. On the product owner’s cue, the estimates are once again revealed:

2, 3, 3, 3, 5, 3

These estimates are much closer together. The team settles for a 3.

The team collectively has a better understanding of the story because of the conversation, which was triggered by a variance in estimates. Ideally, these conversations would happen before the estimation, but sometimes they don’t.

Conclusion

I’d love for there to be another way to ensure that the team is on the same page without having to estimate and then discover that they’re not. I don’t have any good ideas on how to achieve this. If you have any ideas, I’d love to hear them.

Build, Clean, and Rebuild in Visual Studio

Sat, 25 Nov 2017 00:00:00 +0000

In the .NET environment, the process of compiling source code into output files is called building. Two common ways of building are via an IDE, such as the Visual Studio IDE (or the recent Rider IDE from JetBrains), and via the command line using devenv.exe.

If you build via an IDE, you’ll notice that there are three options under the Build menu: Build, Rebuild, and Clean.

They’re pretty straightforward, but have some subtle differences between them.

Build

Build will compile files have changed since the last build. It will only do this for projects that contain files that have changed since the last build. Like I said, pretty straightforward.

Clean

Clean deletes intermediate and output files (e.g. .exe and .dll files), regardless of whether source code files have changed or not.

Rebuild

Rebuild is essentially a Clean and then a Build. It deletes existing output files and performs a build, regardless if source code files have changed or not.

There’s a subtle difference between Rebuild vs. doing a Clean and then a build. Doing a Clean then a Build cleans all projects at once and then builds all projects at once, whereas doing a Rebuild will clean then build each project one project at a time. I can’t think of any circumstances off the top of my head where this would be an issue, but it’s an interesting note.

When to do what

In most cases, doing a Build should be sufficient. If you have a solution with a large project that takes a long time to build, you certainly wouldn’t want to rebuild it every time if you’re not making changes to it. If you’re only making changes to smaller projects that build quicker, Build will be smart and only handle those projects.

Resources

Building and Cleaning Projects and Solutions in Visual Studio

Devenv.exe (MSDN documentation)

The Dreyfus Model and "It depends"

Sat, 27 Feb 2016 00:00:00 +0000

As a software developer, I’ve noticed that experienced developers will often start the answer a question directed at them with “It depends.”

“Should I use inheritance or composition?”

“It depends. Usually composition is better, but it’s not always the best solution. If you have a stable, common abstraction and it’s easy to extend the base class, inheritance may be better than composition.”

“If I want to learn programming, which language should I start out with?”

“It depends. Do you want to make web applications? You should start with HTML, JavaScript, and CSS. Do you want to make mobile applications? Look at Swift or Java. Do you want to do data science? Try a language like R or Julia.”

This may seem obvious but I believe, especially after reading about the Dreyfus model, this habit of saying “It depends” when faced with a particular situation comes from gaining significant experience in software development.

Dreyfus model

I recently read about the Dreyfus model of skill acquisition in the book Pragmatic Thinking and Learning by Andy Hunt. It models how one goes about attaining and mastering skills. In the model, there are five stages of skill acquisition:

1) Novice
2) Advanced beginner
3) Competent
4) Proficient
5) Expert

Let’s look at each of the stages:

Novice

Novices usually are more concerned with accomplishing a task than learning. They just want to get something done. They also don’t have much or any prior experience to help them; they don’t have any knowledge they can make use of in order to know that “When X happens, do Y.” This means that when they make a mistake, it can be very troublesome. Because of this, novices need to follow recipes, sets of context-free rules.

A good example of this is when grandma, who isn’t very good with computers, asks you for help. Grandma says, “My computer is so slow!” You might tell her to restart the computer, which solves the problem. Grandma, who is a novice at computer usage, doesn’t know that her computer is slow because she has 15 applications open and that closing some of those programs to free up resources would solve the problem. To her, she just knows “restarting computer = problem solved”.

But what if the context changes? Maybe grandma has a dial-up connection and is trying to go to www.mygrannybakery.com, which has a lot of images on the their main page. This results in a large amount of data going over her 56k connection, appearing slow to grandma. Well, restarting the computer worked the last time the computer was slow, so why wouldn’t it here? This is an example of where strictly following recipes fails because the context changes. Following these rules will help only to a certain extent.

Advanced beginner

Advanced beginners can start to do some tasks on their own without the aid of recipes, but they still have difficulty troubleshooting when unexpected problems occur. They have more experience than a novice to make use of, but the experience needs to be recent and similar to a problem they’re facing now in order to make use of it effectively. They still don’t have a holistic (big picture) understanding of things.

If you are interested in reading more about this stage, I highly recommend Erik Dietrich’s series of articles on this subject.

Competent

Competents are able to troubleshoot on their own, figuring out problems they’ve never seen before. They still have difficulty with which details to focus on when solving a problem, which can be solved with more experience, but they’re able to mentor novices and don’t need a lot of hand-holding from experts.

Proficient

At the proficient stage, practitioners are able to do a very important skill: self-correct bad behavior. They can self-reflect and analyze how to do better next time. They’re also able to learn from the experience of others. Proficients also understand the big picture.

In my opinion, this is the point where developers start to say “It depends” when asked how to solve a particular problem. This is because, at this stage, practitioners are able to understand and apply maxims: proverbial, fundamental truths that can be applied to the current situation. Maxims are different from recipes in that they are not universal, they need to be applied within a certain context.

For example, look at the maxim “remove duplication in your code.” A novice may interpret this as a recipe and remove ALL duplication in their code. This may lead to some bad abstractions, as discussed in this article by Sandi Metz. Because the proficient has experience, they’re able to to see how a given maxim will work out in a given context. In context A, removing duplication will make the code more readable with no negative side effects whereas in context B, removing duplication will form a bad abstraction that others coming into the code will see and possibly build upon further.

Expert

Experts are primary sources of knowledge in a given field. They’re always looking for ways to improve. They have a lot of experience they can make use of to make the right decisions in the right context. Because of their vast experience, they know how to distinguish important details from irrelevant ones, if even on a subconscious level. A decision to do something can “feel right” even if the expert cannot explain why. This can be due to a combination of past experiences subconsciously influencing their way of thinking.

It depends

So yeah, the general theme here seems to be that as you gain experience, you can look at past experiences and apply those to the current problems you’re facing. As you learn more, you’re able to troubleshoot problems on your own and take given actions in given contexts.

What should you do in a given situation? It depends.

Release With Less Stress

Sun, 07 Feb 2016 00:00:00 +0000

I’ve worked in places where software releases can be an event ridden with stress and anxiety. The cause of this stress comes from several sources, such as pressure to meet a release date, or an issue creeping up in production that was not caught during testing. I’d like to share with you a few steps that you can take to ensure that your release process is less stressful and not such a big deal.

Automate your release process!!

The first thing you should do is automate as much of your release process as possible. Every manual step in your release process is an opportunity for somebody to mess it up. I have been this person on at least one occasion and it’s not a great feeling to be the one who messed up a release.

Less documentation

The more automation there is in the release process, the less documentation needs to exist so people know what to do for the release. In an ideal world, documentation for a release consists of one step (“Step one: push the “Release” button!”).

The problem with documentation is that it can go out of date. A teammate of mine who headed our team’s release followed the release checklist to a T, only to be chastised for doing a step that was no longer necessary. But the release checklist wasn’t updated by the people who modified the release process.

Reduction of handoff between groups

When a release process has a lot of manual steps, there are usually a number of people involved with the process. These people can belong to groups like Dev, QA, and Ops. Steps in the release process may dictate that one group has to hand something off to another. For example, Dev might have to hand their release candidate over to Ops so they can install it on the production servers (this should be automated!). This is an example of where things can go wrong. The wrong deployables could be given to Ops, for instance.

Waiting for a group to do their part involves waiting for them to communicate that they have done their part. If a group does not communicate how things are going on their end, it can be frustrating. I’ve waited for Ops to do their part for over an hour, only to have them say “I see an error” in the Slack channel, with no further follow up. “I see an error” is very vague. What kind of error? Is it something that I, a developer, need to investigate? Communication breakdown between groups can be frustrating.

Automate your release process, folks. Continuous Delivery is a great resource for those who want to do this.

Release smaller pieces more often

Releasing a large chunk of functionality can be nerve wracking. Especially if you’re trying to do so close to a release date that you ABSOLUTELY MUST HIT™. With the clock ticking, people are more prone to getting stressed out and making mistakes, both in writing the software and in releasing the software. However, if you release smaller pieces of software more often, you’ll make it easier to idenfity issues and make it possible to get feedback from the work you’ve already done. Some companies like Etsy are able to release multiple times a day!

Smaller problem search space

Releasing smaller pieces of software more often provides a number of benefits. For one, the problem space of new produciton issues caused by a new release is much smaller. Your latest release caused some production issues, but you’re not sure of the exact cause? Sifting through two weeks of new work is a lot easier than sifting through 6 months of new work. Sifting through half a day of work is much easier than two weeks worth of new work. :)

Shipping earlier

Releasing smaller pieces more often gives you the option to let your customers check out what you’ve done so far and provide feedback. If you don’t want to show your customers what you’re doing, you have the option to perform “dark” releases. This can be done by putting code for new features behind a feature flag. The flag is set to false by default until you want to “turn the feature on.” At that point, you flip the flag from false to true and the new functionality is visible. At some point, you probably want to get rid of the feature flag altogether (delete any if(FeatureFlag) then {//blah} statements) and have the code as a normal part of your codebase.

Releasing pieces earlier also makes releasing not that big of a deal. Did something go wrong with the release? No big deal. Just rollback, fix what was wrong, and try again tomorrow. Speaking of rollbacks, it should be trivial to go back to the last ‘good’ state of your application. You should be able to rollback the application and be able to do so in a short amount of time.

Conclusion

By automating your release process, you remove from it the element of human error. By releasing your software often in smaller pieces, your releases become much more manageable and less of a daunting event. These two courses of action will result in you not getting so stressed out about your releases.

Riffing About Stand-ups

Wed, 20 Jan 2016 00:00:00 +0000

I recently had an experience where my team’s stand-ups were taking almost half an hour to do. They should never go on that long. Thankfully, several people noticed, spoke up about it, and we as a team took steps to resolve the issue. This made me think about stand-ups. I figured, why not write a blog post about my stand-up thoughts and experiences?

For most of my programming career, I have participated in stand-up meetings, or stand-ups. Stand-ups serve as a way for members of a team to update the rest of the team on what they are doing in a concise manner. People stand in a circle, going around and saying what they did. Some people participate in a formalization of this process, referred to as “daily scrums”, taken from the Scrum agile methodology. In Jim Shore’s The Art of Agile Development he explains that participants in a daily scrum answer three questions:

What did I do yesterday?
What will I do today?
What problems are preventing me from making progress?

Stand-ups don’t have to be a once-a-day deal. I have worked in places where we had two stand-ups a day: one in the morning at a designated time and one right after lunch. I’ve also worked in places where we had one stand-up in the late morning once all of the team members arrived in the office. I’ve even worked on a team where we had four 2-hour pairing sessions per day and had a stand-up before each pairing session. It’s all about doing what works for you and your team.

An arbitrary member of the team gives their status update first. Then go around in a circle (clockwise, or counterclockwise, it doesn’t matter) and have each other member of the team give their update. I’ve worked on teams where the developers give their updates first, then QA and business. I don’t like this idea because I think it suggests that somehow devs are more important than QA and business. I don’t believe that at all.

It’s very important that all members of the team stand up during the stand-up. This discourages stand-ups from going on for too long. If people have to stand for a long time, they get tired and want people to wrap it up.

It’s also important that stand-ups are brief. They should consicsely deliver information to the rest of the time and no more. Jim Shore suggests about 30 seconds per person for giving their update. 10 minutes for the whole team is a good max time to shoot for. They really shouldn’t go longer than that. They should not feel like meetings, except that everyone is standing. Personally, I like to keep a “work diary” where I enter the work I’ve done, along with any challenges or triumps I’ve experienced. This helps me remember what information to deliver during a stand-up.

Try to keep non-stand-up-related chitchat before a stand-up to a minimum. While I do think it’s great for team members to shoot the shit with each other (I think this promotes jelling, which is terrific for a team), it increases the time length of the stand-up, taking away from it’s briefness.

There are times when managers of different sorts attend a stand-up. If they tend to have long announcements, it’s important that they go last. That way, members of the team can decide if the information is important to them and stay, or if it’s not and get to work.

Feel free to share your stand-up experiences.

Lessons Learned From Sandi Metz's Practical Object-Oriented Design In Ruby (The First Half)

Mon, 21 Dec 2015 00:00:00 +0000

At work, our reading group has been reading Practical Object-Oriented Design In Ruby by Sandi Metz. At the point of writing this blog post, we are about halfway through the book. Sandi’s book has a number of valuable insights and provides interesting perspectives on OO design. I’d like to share some of what I’ve learned in the course of reading the book.

I’d like to note that even though this book has “ruby” in the title and uses ruby code samples, the knowledge in this book can be applicable to many OO programming languages.

Designing for changeability

Your software WILL change. This is an inevitability.

What’s not inevitable is knowing what the actual changes will be. Some folks predict what changes will be required in the future and design their applications in anticipation for these future, not-yet-determined changes. However, there is no guarantee that these changes will actually have to be implemented.

OO design isn’t about predicting the future. It’s about putting your application in a position where it can easily accommodate future change, regardless of what that change is.

To put it in Sandi’s words: “Design is more the art of preserving changeability than it is the act of achieving perfection.”

I’ve never thought about design this way. I now take this into account when designing software.

Code that’s easy to change

The idea that code should be easy to change is a no-brainer. “Easy to change” is a broad term, though. Sandi gives criteria for code that’s easy to change:

1) Changes have no unexpected side effects
2) Small changes in requirements require correspondingly small changes in code
3) Existing code is easy to reuse
4) The easiest way to make a change is to add code that in itself is easy to change

These criteria resonated with me, particularly 1 and 2. I’ve worked in code where I had to be very diligent about investigating what side effects would be caused by code I changed, which placed a heavy mental load on my brain. I’ve also had experiences where business folks wanted a “small feature change” that “should only be a one line change” that ended up being significantly more effort because the existing code was not easy to change.

In order for code to meet these criteria, Sandi suggests that code has the following qualities:

Transparent - The consequences of change should be obvious in the code that is changing and in distant code that relies upon it
Reasonable - The cost of any change should be proportional to the benefits the change achieves
Usable - Existing code should be usable in new and unexpected contexts
Exemplary -  The code itself should encourage those who change it to perpetuate these qualities

I believe a lot of people already think this makes sense, but it’s great that Sandi has put it into words.

Thinking about applications in terms of messaging

Sandi provides a unique perspective on how objects in an application interact with one another. Instead of thinking about objects calling methods on other objects, think about it like objects sending each other messages.

Managing dependencies

Sandi devotes a chapter in her book to managing dependencies. Dependencies are needed in an application. Objects need to know about each other to some extent in order to communicate. However, objects knowing too much about each other can lead to tight coupling between objects.

An object has a dependency when it knows:

1) The name of another class
2) The name of a message an object intends to send to someone other than itself
3) The arguments that a message needs
4) The order of those arguments

When objects are tightly coupled, they tend to act like one entity. When you use one object, you use them all. The same goes for testing. Consequently, when a change needs to be made to one object, a change usually needs to be made in the other objects. Going back to the criteria of easy to change code, a small change in requirements can result in many changes being made in tightly coupled code. Tightly coupled code is also hard to be reused in multiple contexts.

There are techniques to write loosely coupled code such as dependency injection and dependency isolation.

Dependency injection

When an object’s dependencies are injected, the object knows less about them. Instead of knowing about concrete class names AND method names, an object can just know about the method names that it sends messages to. In a statically typed language like C#, the object will still have to know about interfaces containing the methods it sends message to, but this is a lot more flexible than knowing about concrete types.

Dependency isolation

Sometimes, it may not be possible to perform dependency injection. The next best thing you can do is tightly restrict when dependencies are created and how they are referenced. If you are able to isolate the creation of a dependency into one place, you expose the dependency, making it easier to work with. You also make it easier to refactor code in the future. When you isolate the sending of messages to other objects by wrapping them in wrapper methods, should those dependencies change, side effects are limited to those methods.

Interfaces

Going back to the messages metaphor, objects pass messages to each other. Messages being passed between objects represent the lifeblood of the application. Objects pass messages to each other via their interfaces. Sandi devotes a chapter to creating flexible interfaces.

Asking for “what” instead of telling “how”

Sandi makes use of a great metaphor for interfaces. Imagine a restaurant with customers, waiters, and kitchen staff. The customer says to the waiter, “I want spaghetti.” The waiter gives the spaghetti order to the kitchen staff. They prepare the spaghetti and put in on a plate for the waiter to bring back to the customer.

At each point in the process, there is an interface where one entity communicates with another. The customer knows to ask the waiter for an item from the menu. The waiter knows to place an order for spaghetti for the kitchen staff. The kitchen staff knows to leave a plate of prepared spaghetti for the waiter to pick up and serve to the customer. Each entity knows what they want and they know who to ask for it. And they don’t care how the other entities get that thing to them. The customer doesn’t (and shouldn’t) care that the kitchen staff boils the pasta for 14 minutes instead of 12, or that the sous chef made the sauce instead of the head chef. Also, the customers themselves shouldn’t be in the kitchen stirring the sauce.

If an object knows what to ask for, it relies on less. It knows to ask another object for what it wants and trusts that it will receive it. If an object is dictating to another object how to give it what it wants, it knows more that it should about that other object (and possibly other objects THAT object knows). This goes back to tight coupling. It’s better for an object to ask “what” instead of tell “how.” This will make the objects more loosely coupled.

Conclusion

There’s a lot from the book that I didn’t mention here because I don’t feel like basically plagiarizing the whole book, so I suggest you pick it up and read it for yourself. It changes the way you think about different aspects of OO design. Like I said, we’re only halfway through reading the book and I’ve picked up a lot of great knowledge. Sandi has a way with words and is able to intelligently and concisely communicate her ideas about OO design.

Resources

Practical Object-Oriented Design in Ruby: An Agile Primer