preliminary version

Signed-off-by: Tom Theile <theile@demogr.mpg.de>

code_reviews.md → HowToCodeReview.md

@@ -17,13 +17,13 @@ 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.
 
-## How
+## How to do code reviews
 
-If you want your code to be reviewed, please try to make life easy for the reviewer by making it easy to read your code.
+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
   * 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), [Stata](), (google for *"programming language" style guide*)) and adhere to it.
+  * 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](readme.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.
@@ -41,6 +41,19 @@ If you want your code to be reviewed, please try to make life easy for the revie
 	 * adheres to the style guide
 	 * is simple, understandable
 	 * could be easily optimized
+     * pay attention to special requests of the author
+  * 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
-  * 
+  * the reviewer is not always right, but consider his opinion.
+
+## More information, Links
+
+https://en.wikipedia.org/wiki/Software_architecture
+
+https://en.wikipedia.org/wiki/Code_review
+
+Google Engineering Practices Documentation - https://google.github.io/eng-practices/
+
+List of good resources around code reviews - https://github.com/joho/awesome-code-review

README.md

@@ -1,57 +1,8 @@
-# Git and code review guidelines
+# Good practices in scientific software development at the lab of digital and computational demography
 
+This repository contains several guides on software development at the lab of digital and computational demography:
 
-Git is a distributed version control system.
-It allows you to view and restore old versions of your files and manage the collaborative work on text files.
+[How to request and perform code reviews](HowToCodeReview.md)
 
-
-
-## How to use Git
-
-Git is a command-line program but you can use a graphical user interface if you prefer. Possible GUIs are TortoiseGit (available through the MPIDR software repository in the intranet) or Github Desktop or [many others]( https://git-scm.com/downloads/guis/ ) 
-
-## Writing readme-files
-
-Your code should be usable and reproducible for other researchers.
-That means that you have to include at least a minimal documentation.
-
-A readme-file doesn't need to explain every detail of your software, but it should give the reader concise information about:
- * What is this code about? What does it do? Why would I need it?
- * How do I *use* it?
- * How do I *develop* it?
-
-Nowadays it is standard practise to write readmes in the [Markdown format]( https://en.wikipedia.org/wiki/Markdown ).
-In the next chapter I wrote a structure for a readme that you can use. 
-
-
-### Example Structure
-
-Describe the essence of your software/library/code/snippet/data/whatever in one short sentence.
-
-##### About
-
-Describe what this software is. What it is like, what it is not like. Why is it useful. A picture or a working demonstration would be cool.
-If your software is still in beta-status and still contains many bugs, it would be good to include a warning about the current status.
-
-##### Installation
-
-How do I get started if I want to use the tool?
-What are the prerequisites? How to install them?
-
-##### Usage
-
-Include a basic example which explains the basic functionality in a simple way. You may also include more complex examples
-
-##### Development
-
-If you want that other people are able to contribute to your project, you may need to explain how to set up a suiting development environment. Often times the development is very different than the usage.
-
-##### Citation
-
-If you publish a scientific library, you can ask the users to cite a specific paper if they use it. You can give them the BibTex code for example
-
-##### Licence
-
-A licence removes uncertainty around who may use the software how.
-Look at https://choosealicense.com/ to find a suitable licence.
+[Writing good readmes](writingGoodReadmes.md)
 

usingGit.md

@@ -0,0 +1,11 @@
+# Git and code review guidelines
+
+
+Git is a distributed version control system.
+It allows you to view and restore old versions of your files and manage the collaborative work on text files.
+
+
+
+## How to use Git
+
+Git is a command-line program but you can use a graphical user interface if you prefer. Possible GUIs are TortoiseGit (available through the MPIDR software repository in the intranet) or Github Desktop or [many others]( https://git-scm.com/downloads/guis/ ) 

writingGoodReadmes.md

@@ -0,0 +1,50 @@
+# Writing good readme-files
+Writing good readme-files at the lab of digital and computational demography.
+
+
+
+## Writing readme-files
+
+Your code should be usable and reproducible for other researchers.
+That means that you have to include at least a minimal documentation.
+
+A readme-file doesn't need to explain every detail of your software, but it should give the reader concise information about:
+ * What is this code about? What does it do? Why would I need it?
+ * How do I *use* it?
+ * How do I *develop* it?
+
+Nowadays it is standard practise to write readmes in the [Markdown format]( https://en.wikipedia.org/wiki/Markdown ).
+In the next chapter I wrote a structure for a readme that you can use. 
+
+
+### Example Structure
+
+Describe the essence of your software/library/code/snippet/data/whatever in one short sentence.
+
+##### About
+
+Describe what this software is. What it is like, what it is not like. Why is it useful. A picture or a working demonstration would be cool.
+If your software is still in beta-status and still contains many bugs, it would be good to include a warning about the current status.
+
+##### Installation
+
+How do I get started if I want to use the tool?
+What are the prerequisites? How to install them?
+
+##### Usage
+
+Include a basic example which explains the basic functionality in a simple way. You may also include more complex examples
+
+##### Development
+
+If you want that other people are able to contribute to your project, you may need to explain how to set up a suiting development environment. Often times the development is very different than the usage.
+
+##### Citation
+
+If you publish a scientific library, you can ask the users to cite a specific paper if they use it. You can give them the BibTex code for example
+
+##### Licence
+
+A licence removes uncertainty around who may use the software how.
+Look at https://choosealicense.com/ to find a suitable licence.
+