Antonino Ingargiola edited Coding-style.tex  over 8 years ago

Commit id: 84b517e5db39dddcea02a52450af6b803d9aaccb

deletions | additions      

       

\section{Development style and contributions}  FRETBursts code-base Bugs are an inevitable reality in any reasonably complex software. It  is extensively commented with more that 35\%  of therefore critical to implement countermeasures measures which  minimize  the source code consisting probability  of comments (for comparison the average project  registered on OpenHub has 25\% of comments). introducing bugs and their potential impact~\cite{Prli__2012}.  We strive to follow moder best-practices in software development which are summarized   below.  Indevelopping  FRETBursts, we highly valuethe  source code readability, therefore we follow a property which can   reduce the number of bugs by facilitating understanding and verifying the code.  For this puporpose, FRETBursts code-base is well commented (more that 35\%  of source code),   follows  the \href{https://www.python.org/dev/peps/pep-0008/}{PEP8 python code style rules} rules}.  and the has docstrings in  \href{http://sphinxcontrib-napoleon.readthedocs.org/}{napoleon format}  for the docstrings.  The reference format}.  Reference  documentation is builtfrom the source files  with \href{http://sphinx-doc.org/}{Sphinx} with and  all the API documentation documents are  automatically generated fromthe  docstrings. On each commit,the  documentation is automatically builtby  \href{https://readthedocs.org/}{Read the Docs}  and available online after a few minutes. deployed on  \href{https://readthedocs.org/}{ReadTheDocs.org}.  Unit tests cover most of the core algorithms, ensuring consistency and  minimizing the probability of introducing bugs. The \href{http://travis-ci.org}{Travis CI}  continuous integration service, \href{http://travis-ci.org}{Travis CI}, is used to execute executes  the full test suite after on  each commit. commit, timely reporting errors.  As a rule, whenever a bug is discovered, the fix also includes a new test  to ensure that the same bug cannot happen in the future.  In addition to the unit tests, we include  aspecialized  \href{https://github.com/tritemio/FRETBursts/blob/master/notebooks/dev/tests/FRETBursts\%20-\%20Regression\%20tests.ipynb}{regression-test notebook}  which to easily  compares numerical  results between two versions of FRETBursts is  included in the source tree and periodically executed. Additionally FRETBursts.   Additionally,  the tutorials themselves areperiodically  executed before each release as  an additional test layer  to ensure that no errors or regressions are introduced. Finally, the full set of notebooks used in the multi-spot paper analysis,  including notebooks for extensive µs-ALEX analysis are periodically  re-executed and results compared across executions to ensure that  they agree within the floating point tolerances.  Code readability, rigorous best-practice  development practice style  and extensive testing are all efforts undertaken contribute  to minimize minimizing  the presence of bugs. bugs in FRETBursts.  Bugs that may result in erroneous results will be publicly disclosed as soon as  they are discovered or communicated to us.