Prep for code review

Prepare your project for review

You will sign up for a code review session in class Wednesday, May 14. I will post the code review groups in #announcements on Slack.

At least 48 hours before your code review, complete the following steps.

• Create a file doc/codereview.md containing:

  • A short description of your project (i.e., what you plan for your software to be able to do by the end of the term)
  • A short description of your project's status (i.e., what's working, what's not, etc.)
  • An explanation of how to run your program. This may be just a pointer to your running.md file, which you should update if it needs updating.
  • Questions you would like answered during the code review, if any.
  • Anything else you would like to say about your design decisions, struggles, future plans, etc.
• Make sure your project is in a state where it can be run by a person who follows your running instructions.
• Tag your repo with the tag codereview. Commit and push everything. Note that pushing tags requires a different kind of push, since normal pushing doesn't push tags.
• Once your tag is pushed, post on #general on Slack that your project is ready for code review. Also post a link to your repo. (Even though you've done that before, doing it again will make things convenient for the other students in your code review group.)

Prepare to discuss other people's code

Once your code review partners have posted their links and pushed their tags, do the following.

• Get a clone of their project
• Read their doc/codereview.md
• Follow their running instructions to get their project running on your local system. If you try this for 45 minutes and can't make it work, just stop. You'll be able to report this difficulty at the code review, which will be useful feedback all on its own.
• Read through the code, taking notes.
• Write down a small number (2-4) of things you like about the project, and a small number (2-4) of suggestions. Be ready to share these during the code review session.
• After the code review session, Slack DM your compliments and suggestions to the other team, including Jeff.

What to do during the code review

• When it's your turn to have your code discussed:

  • there's no need to give us background info; you already did that in codereview.md
  • be quiet and listen (which may be challenging for you!)
  • answer direct questions, but briefly

• When we're discussing somebody else's code:

  • show respect; everybody deserves it, and we're all working hard to learn new things, regardless where we are on our learning journeys
  • be kind; code reviews are emotionally charged even in a group of people who already trust each other
  • lead with praise; it's important for people to hear what we think they have done well
  • offer suggestions constructively; use phrasing like "another way to do X is Y, which has advantages Z" rather than "nobody does X anymore" or "X is really bad" or feigned surprise like "you don't know about Y??"
  • express your opinions, but with humility; there's always the chance that you're wrong

Let's have fun!

I find code reviews to be a lot of fun most of the time. We can all learn from each other by talking about our code.