diff --git a/README.md b/README.md index 489cc79..6926f5c 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,57 @@ -# GitGuidelines - How to use Git in our Lab +# 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/ ) + +## 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. + diff --git a/code_reviews.md b/code_reviews.md new file mode 100644 index 0000000..7d3d81a --- /dev/null +++ b/code_reviews.md @@ -0,0 +1,46 @@ +# 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. + +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. + +## Why should we do code reviews? + +* Spot errors that might change the results +* Improve the code (readability, reusability, performance, etc.) +* Learn from each other + +## Types of code reviews + +Big software companies like Google often require a formal code review of every change to the codebase of a product. Special tools integrated into the version control system allow employees to request code reviews only for the changes since the last review. + +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 + +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. + +* 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. + * 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. + * 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 + * 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 + * Be kind but don't hold back. + * read the code (line by line) and check whether the code + * does what it is supposed to do + * adheres to the style guide + * is simple, understandable + * could be easily optimized + +* receive the results + * \ No newline at end of file