From f51714d06dbdc3597b67b70500f8b6d07b009db6 Mon Sep 17 00:00:00 2001 From: Tom Theile Date: Wed, 20 Nov 2019 12:19:45 +0100 Subject: [PATCH] minor improvements --- HowToCodeReview.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/HowToCodeReview.md b/HowToCodeReview.md index dd3df24..8be10b0 100644 --- a/HowToCodeReview.md +++ b/HowToCodeReview.md @@ -1,7 +1,7 @@ # Code reviews at the lab of digital and computational demography -A [code review](https://en.wikipedia.org/wiki/Code_review) is the activity to check the source code of a software with the goal to improve it. -A code review takes time but may save time and headaches in the future. +A [code review](https://en.wikipedia.org/wiki/Code_review) is the examination of source code with the goal to improve the code, the knowldedge of the author and the reviewer. +A code review takes time but saves time and headaches in the future. Do not confuse the code review with a design review (also called architecture review). In a design review you can discuss the architecture (the big structure) of your software. It is possible to formalise this activity by writing a design document which explains the planned structure of your code and submitting this to a reviewer. Ideally, this should happen before the implementation of the software. The design document can contain text and [diagrams](https://www.draw.io/) that explain the whole architecture and the structure of the data flow. @@ -68,12 +68,13 @@ Guidelines derived from scientific group code reviews. E.g.: > * 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. +[Code review guidelines](https://www.codeproject.com/articles/524235/codeplusreviewplusguidelines) by codeproject is a 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 +> > ... [Code Review Guidelines for Humans](https://phauer.com/2018/code-review-guidelines/) - How to do code reviews without destroying relationships. @@ -86,3 +87,4 @@ https://en.wikipedia.org/wiki/Software_architecture https://en.wikipedia.org/wiki/Code_review +The [Clean Code Cheat Sheet](https://www.planetgeek.ch/wp-content/uploads/2013/06/Clean-Code-V2.1.pdf) defines rules for good coding practices.