diff --git a/code_reviews.md b/HowToCodeReview.md similarity index 76% rename from code_reviews.md rename to HowToCodeReview.md index 7d3d81a..f9a6603 100644 --- a/code_reviews.md +++ b/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 - * \ No newline at end of file + * 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 \ No newline at end of file diff --git a/README.md b/README.md index 6926f5c..aa6e287 100644 --- a/README.md +++ b/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) diff --git a/usingGit.md b/usingGit.md new file mode 100644 index 0000000..3bfc4e2 --- /dev/null +++ b/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/ ) diff --git a/writingGoodReadmes.md b/writingGoodReadmes.md new file mode 100644 index 0000000..0216927 --- /dev/null +++ b/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. +