Code Review: Building a sustainable community to talk about coding

This slide deck discusses different types of code review and contains useful information on how to start a group and things to think about when reviewing code

Transcript

1. Code Review Building a community to talk about coding Azalee Bostroem
2. Python in Astronomy 2017 What is code review? • Talking about code; line by line • individual • group • in person • remote 2
3. Python in Astronomy 2017 Motivation • We spend a lot of time coding • Very little formal education • We just talk about the results • Goal: Build a community to discuss coding • If you supervise students - bring this to your meetings • If not - start a group • Participate in code review of open source online projects 3
4. Python in Astronomy 2017 Benefits • Catch Bugs • Improve coding • Get help thinking through design • See different coding styles/approaches • Learn best practices • Learn about new packages and methods • See all levels of code • Know who to talk to • Collection of examples 4
5. Python in Astronomy 2017 Building a sustainable community • Safe • to comment • to share your code • All levels present and contributing • Sustainable time commitment 5
6. Python in Astronomy 2017 Defining your community • Language • People • How often? • Expectations of work prior to meeting 6
7. Python in Astronomy 2017 Choosing your tools • Think about: • Communication • Archiving • Openness • Reviewing 7
8. Python in Astronomy 2017 Getting started • Find a time and a space to meet • Tutorial on tools to be used • Set expectations for discussion • Code review checklist • Give the first presentation 8
9. Python in Astronomy 2017 Running your meeting • 200 lines or less of code for 1 hour • Everyone should be encouraged to present • Moderate discussion • Don’t get hung up on stylistic choices • Avoid stating opinion as fact • Don’t shame raw code • Be careful of assumed knowledge (e.g. jargon or tools) 9
10. Python in Astronomy 2017 What to talk about? • Does the code perform as expected? • Are coding guidelines followed (e.g. PEP-8)? • Is the code easy to read and understand? • Is the code properly documented (e.g. doc strings, references to origin of algorithms)? • Is the code written as efficiently/flexibly as it should be (e.g. hard coded values, use of functions and classes, use of objects)? 10
11. Python in Astronomy 2017 More to talk about • Testing • Licensing • Compare to previous methods • Dependencies • More: see Astropy’s CONTRIBUTING.md on GitHub 11
12. Let’s Try It! • github.com/eteq/pyastro17-code-review • Go to Pull Requests • Go to Files Changed • Select the PR corresponding to your group number • Look over code on your own (5 min) • Talk about comments in group • Add group comments to your PR • Talk about as a group