Why I built Crocodile

I worked at Microsoft for 9 years. If you've ever worked at Microsoft, you've probably used CodeFlow, which is an internal app for reviewing code. A few months into my new job, I found myself missing it, and I know a lot of other ex-Microsoft engineers who feel the same. Reviewing code in GitHub feels clunky and the alternatives I found didn't work the way I wanted. So I started prototyping my ideal code review app on nights and weekends to scratch my own itch and thus Crocodile was born. My initial prototype was pretty embarrassing, but it was enough to prove to myself that what I wanted to build was possible and it motivated me to keep going. Many months and over 400 commits later, I think I have something pretty compelling that you'll love. I've been using Crocodile to review my own code for several months now and I can't go back.

Why should you try Crocodile?

You should try Crocodile if you want to review code fast. Engineering teams spend a lot of time reviewing code and Crocodile streamlines the code review process to help them do it more efficiently. The rise of remote work has made this even more important. At my current job I work with engineers across several time zones. My working hours might not even overlap with theirs, which necessitates asynchronous communication. Crocodile's workflow and UX are designed to help engineers communicate clearly so that the feedback loop is fast and efficient even when they are on opposite sides of the world.

The rest of this blog post goes over the main features that set Crocodile apart, but you don't have to take my word for it. Crocodile is free to use on open source projects. If you want to try it on private projects, you can start a 14 day trial.

Comment on anything

Every code review tool I’ve tried outside of Microsoft limits you to commenting on whole lines. Even worse, GitHub only lets you comment on lines that have changed. Sometimes I want to point out something the author missed in an unchanged part of the file but GitHub makes it impossible to do directly.

Screenshot of comment on a part of a line

Crocodile lets you comment on any part of the file, even if it’s just a single character. Being able to comment on the exact text removes ambiguity because you don't have to explain which part of the line you're commenting on.

Floating comments

Almost all code review apps put comments inline with the code, which is a huge pet peeve of mine. I find this makes code really difficult to review because it breaks up the flow of code. This is especially bad when whitespace matters (looking at you Python and YAML). Trying to tell if code above and below a code review comment are at the same indentation level shouldn't be a problem.

Screenshot of floating comments

Crocodile displays comments differently. Comments are in floating windows with lines that connect them to the code being commented on. These comment windows can be repositioned by dragging, or minimized to keep them out of the way.

Per comment thread statuses

Communication between the author and reviewers is key to a successful code review. To make sure everyone is on the same page, every discussion has a status to indicate whether it has been addressed and if everyone is satisfied with the outcome. Crocodile’s comment lifecycle looks like this:

  1. A reviewer leaves a comment with the initial status of Open.
  2. The review author changes the status to Resolved when they feel they have addressed all the issues raised in the comment.
  3. The original commenter reviews the changes and either sets the status to Closed if they are satisfied or Open again if more changes are needed.

Having statuses makes it clear where each person stands so there aren’t disagreements later about whether something was properly resolved.

Comparing iterations

Screenshot of iteration comparison UI

The code is likely to change in reaction to feedback over the life cycle of a review. Crocodile makes it simple to compare iterations to see what has changed since the last time you looked at the review.

Transferring comments across iterations

Something I took for granted in CodeFlow was its ability to transfer comments across iterations. GitHub will often hide and mark comments as outdated when the code has only changed slightly. For instance, renaming a variable on a commented line will cause GitHub to mark the comment as outdated and it won’t be visible on the latest iteration, which means engineers are wasting time hopping between iterations to respond to comments, or worse, the comment gets lost and never resolved.

Screenshot of comment transferred across iterations

As new iterations get pushed to the review, Crocodile maps previous comments to the new code so that they don’t get lost and you can quickly see if the comment has been addressed. In the screenshot above I'm comparing iteration 4 and 5. Bjorn commented on nil in iteration 4 which was replaced by err in iteration 5, but Crocodile is able to map the comment selection even though it changed.

When did they approve?

The code in a review can change significantly even after someone has already approved it. Perhaps the requirements changed or a defect was found. Regardless, in these cases you may want to ask reviewers to take another look.

Screenshot of reviewer statuses

Crocodile makes it simple to see the last time each reviewer looked at the review so you can see who approved an outdated version of the code.

Threaded comments

Screenshot featuring threaded comments

Sometimes a comment discussion can diverge into separate topics and it can be difficult to manage in a linear discussion. Crocodile supports threaded comments so you can reply to specific messages and fork discussions as needed.

See what’s new

Screenshot featuring new comments

Comparing iterations helps you see what code changed, but it doesn't help you track conversations. Crocodile highlights new comments you haven't seen. It also has a dedicated comments page where you can quickly view all comments in the review. This lets you quickly respond to each one without having to switch files constantly.

GitHub integration

Crocodile integrates with GitHub seamlessly by automatically creating reviews for GitHub pull requests. A link to the Crocodile review is added to the GitHub pull request as a comment to make it easy to find.

Try Crocodile today for free

And that's it! I hope you'll give Crocodile a try. There's a ton of other features that I'd like to add in the future and if there's something you'd like to see added, drop me an email.

Author profile picture
James Lao