minor corrections

HowToCodeReview.md

@@ -3,7 +3,7 @@
 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.
 
-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.
+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.
 
 ## Why should we do code reviews?
 
@@ -17,25 +17,28 @@ Big software companies like Google often require a formal code review of every c
 
 Small software development teams sometimes favor the more informal *over the shoulder* (OTS) code review. During an OTS review, the programmer explains his code to the reviewer who will ask questions, ask for changes or clarifications.
 
+In our lab we work on very different projects. Therefore it might be useful to start with an OTS-review where the author explains the structure of the program to the reviewer. Later, a formal code review is helpful for a look at the details.
+
 ## How to do code reviews
 
 If you (the author of code) want your code to be reviewed, please try to make life easy for the reviewer by making it easy to read your code.
 
-* prepare your repository
+* Prepare your repository:
   * you may want to review the code by yourself first. Ask yourself the question: will someone else be able to understand what you want to do in every line of code?
   * programming languages can be written in a specific *style*. Use a good *style guide* for your language ([Python](https://www.python.org/dev/peps/pep-0008/), [R](http://adv-r.had.co.nz/Style.html), (google for *"programming language" style guide*)) and adhere to it.
   * make sure your code does not depend on very specific requirements that are only met on your PC.
   * write a readme-file. Read [this guide](writingGoodReadmes.md) on what should be included in a readme-file.
   * use [Git](https://git-scm.com). This allows us to do incremental code reviews. It also shows you what the reviewer changed.
   * use Git and [Github](https://github.molgen.mpg.de/) for bigger projects to allow incremental code reviews with the tools of Github.
 
-* find someone who is willing to do a code review for you
+* Find someone who is willing to do a code review for you
   * it is easier to do several short reviews. Ask early!
   * Make the reviewers life as easy as possible by writing simple code, good comments and a good readme/documentation.
   * the reviewer should know the programming language. He/she should also know and understand the problem that this software tries to solve.
 
-* The duties of the reviewer
+* The duties of the reviewer:
   * Be kind but don't hold back.
+  * really: be kind!
   * read the code (line by line) and check whether the code 
      * does what it is supposed to do
 	 * adheres to the style guide
@@ -45,7 +48,7 @@ If you (the author of code) want your code to be reviewed, please try to make li
   * you can edit the code in place, add a comment next to the specific code line and write broader thoughts in one statement.
   * if your comment is not essential for the functionality but more educational, preface the comment with "nit:".
 
-* receive the results
+* Receive the results
   * the reviewer is not always right, but consider his opinion.
 
 ## More information, Links