Merge branch 'codequal2turingway' of github.com:NLeSC/guide

best_practices/checklist.md

@@ -2,22 +2,22 @@
 
 Here we provide a short checklist for software projects, the rest of this chapter elaborates on the various point in this list.
 
-
 The __bare minimum__ that every software project should do, from the start, is:
+
 * Pick & include an [open source license](licensing.md)
-* Use [version control](version_control.md) 
+* Use [version control](version_control.md)
 * Use a [publicly accessible](version_control.md#repositories-should-be-public)
- version control repository 
-* Add a [readme describing the project](documentation.md#readme) 
-
+ version controlled repository
+* Add a [readme describing the project](documentation.md#readme)
 
 We recommend that you also do the following (from the start of the project):
+
 * Use [code quality tools](code_quality.md)
 * [Testing](testing.md)
 * Use [standards](standards.md)
 
-
 Additional steps depend on the goal of the software (zero or more can apply):
+
 * [I'm publishing a paper](#im-publishing-a-paper)
 * [I'm expecting users](#im-expecting-users)
 * [I'm expecting contributors](#im-expecting-contributors)
@@ -28,26 +28,16 @@ Additional steps depend on the goal of the software (zero or more can apply):
 * [Make your software citable](../citable_software/making_software_citable.md)
 * Cite DOI in paper 
 
-
 ## I'm expecting users
 
-* [Release](releases.md) your software 
+* [Release](releases.md) your software
 * Provide [user documentation](documentation.md)
-* [Easy installation](releases.md#one-command-install) 
+* [Easy installation](releases.md#one-command-install)
 * Provide issue tracker
 
-
 ## I'm expecting contributors
 
 * Provide [development documentation](documentation.md#source-code-documentation)
 * Provide a [means of communication](communication.md#discussion-list)
 * Implement and add a [code of conduct](documentation.md#code-of-conduct)
 * [Contribution guideline](documentation.md#contribution-guidelines)
-
-
-
-
-
-
-
-

best_practices/code_quality.md

@@ -1,66 +1,16 @@
 # Code Quality
 
-There are several ways to improve software quality and find bugs quickly and easily.
-By following a set of conventions, code will look 'cleaner' and be more understandable.
-It will also help spot syntax errors and other errors early, without having to run or compile all the time.
+Ways to improve code quality are in the [Code quality](https://the-turing-way.netlify.app/code_quality/code_quality.html) chapter on the Turing Way.
 
-## Coding style
-
-A coding style gives guidance on those parts of programming that are irrelevant to the compiler or interpreter.
-For instance, what do you call your variables? do you use spaces or tabs for indentation? Where do you put comments? etc.
-
-Here is a very nice article about why coding styles matter, and increase software quality:
-[Improving software quality, why Coding Style Matters](http://coding.smashingmagazine.com/2012/10/25/why-coding-style-matters/)
-
-For style guides see the different languages in [the Language Guides](language_guides/languages_overview.md).
-Google has a style guide for most languages [google style guide page](https://code.google.com/p/google-styleguide/).
+There are [online software quality improvement tools](https://the-turing-way.netlify.app/code_quality/code_quality.html#Online-services-providing-software-quality-checks) see the [language guides](language_guides/languages_overview.md) for good options per language.
 
 ## Editorconfig
 
-Use [editorconfig](http://editorconfig.org/) to adhere to the basic code style rules.
-
-Using editor config is not necessary, but saves a lot of time and keeps developers from straying
-from the style of choice and helps to avoid some problems caused by formatting differences
-(line ending, tabs vs spaces).
-
-There is support for editorconfig in most editors.
-The [Editorconfig website](http://editorconfig.org/) provides plugins for your editor of choice.
-If you use eclipse, use [this plugin](https://github.com/ncjones/editorconfig-eclipse).
-
 The eScience Center has a [shared editor config file](https://raw.githubusercontent.com/NLeSC/exemplum/master/.editorconfig)
 
-## Automatic code formatters and linters
-
-These are small programs that check if your code follows a specific coding style.
-Some code formatters can find more issues (unused variables, missing documentation, ...)
-They are often langauge dependent, and can be integrated with an editor.
-
-## Online software quality improvement tools
-
-There are several web services that analyze code and make the quality of the code visible.
-
-Code quality analysis services are web applications which have the following features:
-
- * Automaticly analyse your code after a Github push
- * Usually free for open source projects
- * Most supports multiple programming languages, but not every language will have the same level of features
- * Grade or score for the quality of all of the code in the repository
- * List of issues with the code, grouped by severity
- * Drill down to location of issue
- * Default list of checks which the service provider finds the best practice
- * Can be configured to make the list of checks more strict or relaxed
- * Can be configured to ignore files or extensions
- * Can read configuration file from repository
- * Tracks issues over time and send alerts when quality deteriorates
- * Optionally reports on code coverage generated by a CI build
-
-See the [language guides](language_guides/languages_overview.md) for good options per language.
-
-For a list of choices see http://shields.io/ or https://github.com/ripienaar/free-for-dev#code-quality
-
 ## Name spaces
 
-If your language supports namespaces, use **nl.esciencecenter**
+If your language supports namespaces, use **nl.esciencecenter** or better a namespace based on the project.
 
 ## Code reviews
 

best_practices/documentation.md

@@ -51,9 +51,11 @@ Ideally in README.md
 ## Source code documentation
 
 ### Code comments
+
 Code comments, can be block comments or inline comments. They are used to explain what is the piece of code doing. Those should explain why something is done in the domain language and not programming language - why instead of what.
 
 ### API documention
+
 API documentation should explain function arguments and outputs, or the object methods. How they are formulated will depend on the language.
 
 ## Usage documentation
@@ -83,21 +85,23 @@ Guidelines should be made available once the code is available online and there
 for contributions by other people. Good guidelines will save time of both lead
 developer and contributor since things have to be explained only once. A good CONTRIBUTING.md
 file describes at least how to perform the following tasks:
-- How to [install the dependencies](#documented-development-setup)
-- How to run [(unit) tests](testing.md#unit-tests)
-- What [code style](code_quality.md#coding-style) to use
-- Reference to [code of conduct](#code-of-conduct)
-- When using a [git branching model](version_control.md#choose-one-branching-model), the choice of branching model
+
+* How to [install the dependencies](#documented-development-setup)
+* How to run [(unit) tests](testing.md#unit-tests)
+* What [code style](https://the-turing-way.netlify.app/code_quality/code_quality.html#Code-style) to use
+* Reference to [code of conduct](#code-of-conduct)
+* When using a [git branching model](version_control.md#choose-one-branching-model), the choice of branching model
+
 An extensive example is [Angular.js's CONTRIBUTING.md](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md). Note that [GitHub has built in support for a CONTRIBUTING.md file](https://github.com/blog/1184-contributing-guidelines).
 
 ## Code of conduct
 
 A code of conduct is a set of rules outlining the social norms, religious rules and responsibilities of, and or proper practices for an individual. Such a document is advantagous for collaberation, for several reasons:
+
 * It shows your intent to work together in a positive way with everyone.
 * It reminds everyone to communicate in a welcoming and inclusive way.
 * It provides a set of guidelines in case of conflict.
 
-
 [contributor covenant](http://contributor-covenant.org/)
 
 CofC should be attached from the beginning of the project. There is no gain from having it with one
@@ -145,6 +149,7 @@ Read more in [the blog post by Druskat et al.](https://software.ac.uk/blog/2017-
 ## Print software version
 
 Make it easy to see which version of the software is in use.
-- if it's a command line tool: print version on the command line
-- if it's a website: print version within the interface
-- if the tool generates the output: output file should contain the version of software that generated the output
+
+* if it's a command line tool: print version on the command line
+* if it's a website: print version within the interface
+* if the tool generates the output: output file should contain the version of software that generated the output