From 016b96ac388bd96427a1f5c90d6354e4a597ee7c Mon Sep 17 00:00:00 2001 From: Tom Theile Date: Tue, 19 Nov 2019 16:39:42 +0100 Subject: [PATCH] better (?) quoting --- HowToCodeReview.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/HowToCodeReview.md b/HowToCodeReview.md index 94056f9..dd3df24 100644 --- a/HowToCodeReview.md +++ b/HowToCodeReview.md @@ -54,28 +54,27 @@ If you (the author of code) want your code to be reviewed, please try to make li ## More information, Links [Code Review For and By Scientists]( https://arxiv.org/pdf/1407.5648v2.pdf ): Abstract: -"We describe two pilot studies of code review by andfor scientists. Our principal findings are that scien-tists are enthusiastic, but need to be shown code re-view in action, and that just-in-time review of smallcode changes is more likely to succeed than large-scaleend-of-work reviews." +> We describe two pilot studies of code review by andfor scientists. Our principal findings are that scien-tists are enthusiastic, but need to be shown code re-view in action, and that just-in-time review of smallcode changes is more likely to succeed than large-scaleend-of-work reviews." [Code reviews: the lab meeting for code]( http://fperez.org/py4science/code_reviews.html ) Guidelines derived from scientific group code reviews. E.g.: -"The most difficult part of writing code is always to make it understandable to other people, including yourself a few months down the track. There’s certainly no shame in finding out that your code wasn’t as easy to understand or use as you’d hoped, so don’t take it personally when it happens (which it always does, at least in my experience), but treat it as an opportunity to improve. - -Here’s some general guidelines for making your code review go smoothly: - - * Make sure the motivation for your code is clear. Someone who isn’t intimately involved with your project should understand from the module documentation and the comments what you are trying to do, what approach you’re taking, and why they should expect it to work. - * Take some time to prepare a presentation about your code that will answer the above questions even for someone who hasn’t read the code. You’re more likely to get useful feedback, rather than nitpicking about syntax, if the audience can see the big picture. - * Get the code sent out at least a few days beforehand along with some background about what to look at (if large), whether suggestions should be about architecture/implementation/algorithm/requirements, etc. Make sure everyone has enough time to read the code beforehand, and don’t send a series of updated versions immediately before code review. - * Don’t try to present too much. 200 lines is an absolute maximum – 50 is usually more reasonable. - * ... -" +> The most difficult part of writing code is always to make it understandable to other people, including yourself a few months down the track. There’s certainly no shame in finding out that your code wasn’t as easy to understand or use as you’d hoped, so don’t take it personally when it happens (which it always does, at least in my experience), but treat it as an opportunity to improve. +> +>Here’s some general guidelines for making your code review go smoothly: +> +> * Make sure the motivation for your code is clear. Someone who isn’t intimately involved with your project should understand from the module documentation and the comments what you are trying to do, what approach you’re taking, and why they should expect it to work. +> * Take some time to prepare a presentation about your code that will answer the above questions even for someone who hasn’t read the code. You’re more likely to get useful feedback, rather than nitpicking about syntax, if the audience can see the big picture. +> * Get the code sent out at least a few days beforehand along with some background about what to look at (if large), whether suggestions should be about architecture/implementation/algorithm/requirements, etc. Make sure everyone has enough time to read the code beforehand, and don’t send a series of updated versions immediately before code review. +> * Don’t try to present too much. 200 lines is an absolute maximum – 50 is usually more reasonable. +> * ... [Code review guidelines](https://www.codeproject.com/articles/524235/codeplusreviewplusguidelines) by codeproject is document like this one and explains the why and how with practical tips for reviewers and authors. [11 best practices for code review]( https://www.ibm.com/developerworks/rational/library/11-proven-practices-for-peer-review/index.html) - 1. Review fewer than 200–400 lines of code at a time - 3. Take enough time for a proper, slow review, but not more than 60–90 minutes - 4. Be sure that authors annotate source code before the review begins -... +> 1. Review fewer than 200–400 lines of code at a time +> 3. Take enough time for a proper, slow review, but not more than 60–90 minutes +> 4. Be sure that authors annotate source code before the review begins +> ... [Code Review Guidelines for Humans](https://phauer.com/2018/code-review-guidelines/) - How to do code reviews without destroying relationships.