Don’t Make Me Think, When I Consume Your API

I recently worked on the voucher badge feature.  I needed to create an api endpoint to consume the voucher count, because we use services.

Unused Voucher Badge
The first iteration, the api passed voucher objects. However, I decided to refactor and pass the voucher count and less data between services, in hopes to shave couple milliseconds off load time. My first refactor looked like the following. Looking at the code, I know exactly what is happening and what data is being passed. It’s simple. 
unused voucher count as integer
Now imagine you’re consuming this new endpoint for the first time, with no knowledge of the implementation. You receive the following json object.  You might think, “Seven? what the hell does seven mean?” Then you’ll inevitably follow the source to VoucherController in order to understand.   

Instead, why not be explicit? Make it clear to everyone who consumes your lovely api what their getting back.

unused voucher count as a hash

That is so much better! Now I don’t have to visit the Api and look at the source code in order to understand what the object is.

So why not make others happy by telling them what their consuming, instead of making them think. Make your api intention explicit!
[EDIT]

Lets take this one step further and change our controller name as well. To be clear the vouchers controller only had one job of grabbing all unused voucher and returning the count. If it was part of a larger vouchers controller, I would have refactor it out instead .


Not only are we explicit with the object that is being returned, but the API name. I think this gives a better explanation of the api.

This post was based on a lightning talk I planned on giving at RubyConf 2014. However, the talks were cut short so I decided to make a blog post about it instead.

Standard

Refactoring And Building The Next Big Thing

Code refactoring is the process of restructuring existing computer code – changing the factoring – without changing its external behavior


Refactoring is important and necessary, but many times it gets pushed to the backlog. I want to make three point with this post. Why refactoring isn’t taken seriously. When to refactor. And changing refactoring habits. 

As developers, we are paid to build features and fix bugs to increase value for customers. From the project managers point of view, refactoring does neither one of them. So we can say that refactoring is for the developer. This realization gives us insights to why the time allocated to refactor, is so minimally. The PM’s would rather see new feature and bug fixed instead. Code doesn’t get refactored. We keep digging the hole deeper and deeper.


So when should we refactor? If we’re constantly swamped with tickets from our PM we’ll never have time to refactor. The solution? If we’re not given adequate time, we need to refactor in small batches. Tickets should be completed along side small incremental refactoring. This helps us release features reasonably and fix parts of the code. These little batches are now easier to work with and speeds up development time. These refactoring should be within the files we are currently working in. We shouldn’t go out of scope. This will keep us grounded to meet our deadlines.

These are some habits I have learned throughout out the months (1 year in November; Yay!). First following the TDD way (red, green, refactor). As a professional this didn’t fit our team’s agile approach. We refactor but test doesn’t drive our design. Next refactoring in chunks. Asking for time to refactor and going through our codebase to clean up dead code and smelly implementations. To be honest, this doesn’t happen to often. There is little time. So we end up having a larger than necessary codebase with dirty implementations.

I recently began refactoring while creating features and it’s been going great. I’m still not satisfied with the codebase, but I see little win’s over the map. This makes me happy as a developer. 

Credits goes to Ronald Jeffries, 3 founders of the Extreme Programming (XP), for inspiring me to think of refactoring in a different light. His original blog post can be found here: http://xprogramming.com/articles/refactoring-not-on-the-backlog/

Standard

How To Have Effectively Code Reviews

Code reviews can be a daunting challenge for developers. It’s hard to know what to look for in a given pull request (PR). I want to share some tips that I have learned from other LivingSocial engineers.

Questions you should be asking about the PR

  1. Do you understand what the PR does?
    • Does it have a clear commit message?
  2. Do you understand how the code accomplishes the goal?
  3. Is the new code tested? 
    • If it’s a big new feature, is it covering edge cases?
  4. Does the code use obscure syntax, how could it be more clear or less obscure? 

Must Do

  1. Does the entire test suite code pass?
    • Run the full test suite, and not only the one controller that changes
  2. Pull down and rebase so that your newest commit is on top
    • This way if you need to rollback your commit, you don’t have to shift through multiple commits to get to yours
  3. Worst case scenario back up plan
    • If all goes to shits, what are the steps the merger should take to undo this shenanigans
  4. Don’t dilly dally when you see a PR. Be as responsive as you can in order to have an effective feedback loop. 

This is a good start for effective code reviews and merging pull requests. These steps have helped us find bugs, code smells, and fast cycles for a better engineering experience. 

If your team has other methods for effective code reviews, please share down below.
Cheers!
John  

 

Standard

Free Private Git Repositories

As a software developer, I decided it’s time to upgrade my swag and purchase private repos so that I can keep my entrepreneurial / side projects in the down-low. I went ahead and purchased the micro plan. If I ever need more than 5 repos, I would always upgrade and pay the difference. No hassle.

I’ll say it out right I love Github. Every since I got indoctrinated into the programming community I have been using GitHub. It was free, and easy to use. Everyone seemed to use it. I haven’t looked back, until now.

After purchasing my first private repo and feeling good about being a real developer, my mind went crazy and started wondering if there is a world outside of GitHub and what my other choices could have been.

There are options!

List of Free Private Repositories (in no particular order)

If I had to start over, I think I will go with gitlab. It’s open-sourced, seems well maintained, and it provides much more space than the other free hosts. Many of the free git repositories limit your file size between 0.5 to 2 gb.

The beauty of git is that as long as these services use git and not mercury, I can always switch over. It’s Git all around. You might have to learn new commands to push code up to the repository, but in the end it does the same thing.

Long Live Git.

Standard

Become A Better Programmer By Reading

There are countless resources online to become a better programmer. From doing katas, watching conference talks, building applications, reading, etc. This post will focus on the importance of reading.

This is an example of how you might see programming as a junior developer. When you face a new problem you go through many iterations for a solution. Once you figure it out, you’re content and move on with your other tasks. Fast forward couple weeks, and you’re faced with a similar situation. You realize that you’ve faced this issue before and solve it in a similar way, and you’re happy it works. Then you move on.

This is one of the most compelling reasons that you need to broaden you’re knowledge. When there are many ways to solve a problem, how would you know that you’re solution is best? You don’t. Having a large set of knowledge helps you make sound decisions. By reading blogs, articles, and lines of code, can help you gain knowledge quickly.

I’m not saying that your first implementation is shit and it isn’t right. Who know’s it may be the best solution for your situation. My point is that you won’t have a clue without having any alternative solutions.

Here are favorite tools to learn through reading

  •  Reading my co-workers pull requests. I like to take time and read what problem they were solving (commit message), and then reading each changed line. Open Source projects works well too!
  • Ruby Weekly. If you’re not signed up for the news letter I highly recommend you do that now. Peter Cooper curates articles, tutorials, and tools to help you develop in Ruby. This way, I don’t have to search the web for quality content
  • Books are your best friend
Standard

Managing Time For Yourself

One of the hardest things you face as a junior software developer is managing time. You constantly find yourself on a “quick” google hangout, a “simply” feature request, or a bug fix. Up until now, you haven’t said no to a “can you help me figure this out” request. You finally said no, because you have shit to do!

Don’t get me wrong, you probably believe helping each other is vital to your teams success. It’s important that you spend time knowledge sharing, and moving past roadblocks. It’s important to pair with senior developers. It’s a faster way to learn the codebase, as well as, better practices.

However, you can’t say yes to everything. You have deadlines you promised to meet. This requires time and effort so that you can write code that has test coverage. This means you need to focus on your work and get it done. You’re not helping anyone if you can’t hit your deadlines yourself.

Standard