MIB-good-coding-practices.md

 This page is not meant to tell you all about general coding practices but it aims at listing points that we (MIB bioinfo) find important. The ultimate goal is to improve code readability and make it easy for others to work with or modify our scripts. It is good to take a look at this page before starting sharing your code. The coding conventions of the language you use to develop always applies unless stated differently in this document.
 
-> for idx >= 1 becomes for 1 <= idx
-
 Naming rule
 ---------------------------
-
 **Meaningful name:** Variable names should be easy to understand, short and representative of the data they store. The way you name your variables is key to making your code readable. Make variable names self-explanatory and consistent with the theme of the script.
 
 **Short name:** Try making the variable name as short as possible, avoid the use of separators like (- _ / \ & + . ,) in the variable names. Follow the [camelCase](https://en.wikipedia.org/wiki/Camel_case) notation and variable name always starts with lower case.
 
+**duplicates:** Avoid duplicating variable name when it is not needed. Update the value of variable without the name makes it easier to track the variable and the different transformation applied to it.
+
 **For example:** If you write a script to assemble 'FASTQ' files, avoid using variable like, input1 input2 rather call it what it is forwardRead, reverseRead or fastqFile.
 
 **Function & Class:** Function and Class name follow the same idea as for variable name with the exception that for class names the 1st letter is capitalised.
 For example, thisIsFunction but ThisIsClass.
 
-
-
 Documentation & comments
 --------------------------
-
-Comments are parts of your script that are never interpreted by the computer and Documentation is a specific part of the comments that describes general purpose of the entire script or just specific functions. Documentation are more formal and can sometimes be used to general manual.
+Comments are parts of your script that are never interpreted by the computer and Documentation is a specific part of the comments that describes general purpose of the entire script or just specific functions. 
+Comments are used to make parts of the code easy to understand, it helps when updating the code. So BE CLEAR & CONCISE.
+Documentation are more formal and can sometimes be used to general manual.
+Here is the minimum amount of documentation we would like every code to embed (this is formatted for python so please change the format if you use documentation style like perldoc, doxygen...).
 
 ```
 USAGE
 -----
-Here comes an example of a short command that could be used to test the script
-template.py -i ../test-data/input.file -o ../test-data/output.file [--threshold 2]
+This part says which command to use to test your code.
+Optional parameters should appear between brackets
+scriptName -o REQUIRED_OPTIONS [--optional OPTIONAL_PARAMETERS]
+
+OUTPUT(S)
+---------
+A short description of the output format.
 
 DESCRIPTION
 -----------
-This script is a template that give an idea what a shared MIB script should look like.
-Please modify it to your taste.
-This section should have an extensive description of what the script does, it will be 
-used to make a list of all the scripts and their description.
-
-It is important that your script uses python 3.6
+Here comes a larger description of the purpose of the script. This description will be used to make a page that list all scripts so please be clear and concise.
 
-PROGRAMS
---------
+EXTERNAL PROGRAMS
+-----------------
 Which third parties program are used in this script.
 
 AUTHOR(S)
@@ -45,10 +44,24 @@ AUTHOR(S)
 Will Iam, will.iam@wur.nl
 ```
 
+Spaces & Indentations
+---------------------
+The use of spaces and line break are very important to improve the readability of your code but it needs to be used in the right place with the correct amount. Avoid using several consecutive spaces to separate parts of your code only 1 space is enough. Avoid using unnecessary space at the beginning of a line.
+Indentation can be made with 2 or 4 spaces (we recommend using 2), be consistent with your indentation.
+1 line break should be used to separate 2 different code blocks, for example between 2 functions should be a line break. Using too many line breaks can deteriorate the readability of your code.
 
-Indentations
 Portability
-Reusability and scalability
+-----------
+Portability is the possibility of a code to be run on multiple platforms and environment. For example, just imagine writing a script that uses a variable that is never changed in the coded (this is called a hard-coded variable). That variable encodes for a location that is specific to your personal machine for example /Users/username/nowhere, this script cannot be used on a different machine than yours and probably not by a different person than yourself. Avoid hard coded variables when coding to ensure anybody can use it.
+**Portability of in and output:** We can enlarge the notion of portability to the input and output, try working with file formats that are known and that could be used on any platform. For example, instead of XLSX files use a CSV or TSV file. Describe the structure of your file in the description if it is custom.
+
+Modularity
+----------
+Writing script in small blocks helps maintaining or extending it. We recommend breaking big code into small functions that does only 1 precise operation. A good function usually holds in max 20 lines of code.
+Using functions and classes make it possible for others to build their ideas using what others have already done.
+
 Testing
+-------
+For every shared script, we expect a small test data to be present in the folder _test-data_ inside the script directory or in the pipeline directory. The _USAGE_ section of the documentation tells users how to perfom a test based on those test datasets.
+A test should take less than 15min.
 
-https://www.thinkful.com/blog/coding-best-practices/
\ No newline at end of file