Here's a situation I've encountered numerous times:
We're interviewing an engineering candidate. Say they've finished a course, a bootcamp or even worked for 1-2 years. I give them a home assignment to check their coding abilities. Now - we always ask to submit the assignments as Github pull requests - this both makes it easier to review and provides a simulation of an actual collaborative workflow.
They submit their work - and that's when I suddenly realize - they don't know how to work with git!!!
I've stumbled upon this time after time and finally decided it's time to summarize my expectations in a post.
Git is a Communication Tool, not just Code Storage
IMHO - this is the most profound realization. Source control isn't just there to store and backup versions of code. It's also the medium to communicate the decisions and actions we take while coding. To our future selves as much as to others.
And we want this communication to be effective of course.
So here are some rules of effective Git communication:
A few folks I respect noted that the rules here talk mostly not about Git per se - but about features offered by Git repo managers - such as Github, Gitlab or BitBucket. In theory - as a coder you may be expected to be able to work with Git without any repo manager. But in practice - you're gonna be using a repo manager anyway. So the rules still apply!
1. Explain yourself
Start with commit messages
Tons of posts have been written on the importance of good commit messages and still - most commit messages out there lack clarity and detail. For some tips on how to make your own commit messages great - check out posts here on dev.to - here's a good example
Continue with PR description and comments
Often your pull request (further abbreviated as PR) will have a number of commits in it. Sometimes this makes sense, sometimes not - more on that later. An important thing to remember is you can name the PR and provide a description for it - summarizing the work you've done and pointing the reader at whatever you feel is important in your work.
Further on - you can provide comments and tag other users both in description and comments using the '@' sign.
(More on this in section 2 - the one about Markdown.)
Assign reviewers
This looks obvious except it clearly isn't. Many folks create a PR and then send me the link to it - in email or Whatsapp.
You don't need to do that!
Just make me a PR reviewer and Github will make sure to notify me.
2. Use Markdown
Structure your PR comments
Your PR description and comments aren't limited to plain text (as commit messages are). You can structure text with #headings, make it bold or italic, tag folks (@otomato) provide hyperlinks and even include images. 
Add READMEs
If you feel like your work needs more documentation (user guide style) - it's always a great idea to accompany your code with an *.md file - all Markdown and now also version controlled (as opposed to PR comments)
3. Reduce Noise
Squash your commits
It's clear that any serious coding work requires a lot of trial and error. It's also only natural to commit on every change - this way we iterate fast and check ourselves continuously. But! When we submit our work for review - the multitude of our attempts isn't of any interest. It's a distraction!
Even though Github now allows to automatically squash commits when merging a PR - it's a good etiquette to learn working with interactive rebase and squash your commits before submitting code for review.
This is how you show respect for your own work and for the reviewers attention - by providing a clean history with only the stuff that matters.
Don't comment out - just delete!
This is also a pattern we see a lot. Folks are somewhat afraid to remove code entirely. So they just comment stuff out and submit it like that. But this makes reading code so much harder. Comments are there for a reason - they exist to provide additional information. Not to store old code "just in case". You have git history for that!
So before submitting a PR - please make sure you've removed all code commented out while debugging and coming up with a working solution.
4. Provide feedback
And finally - if your reviewer left comments - they will appreciate feedback. Don't just fix everything as you find fit and then submit the results for re-review. Reply to each comment with a few words - explaining what and how you fixed - keep the conversation flowing.
These are my tips for effective Git communication.
Did I miss anything? What else would you add?
Leave your feedback - and I promise to reply - after all (as you could tell) I value effective communication above all else.
Cover photo by Andrea Piacquadio from Pexels.com
Top comments (0)