docs/development/Development.md

   1 # Development
   2
   3 This document is primarily for developers only.
   4
   5 ## General principals
   6
   7 1. Name everything well.
   8 2. Strike a balance between simplicity and not-repeating code.
   9 3. Methods that start with the word 'find' can return a null, methods that start with 'get' should not.
  10 4. Keep methods short - it makes it easier to test.
  11 5. Don't be afraid of moving code to a new file - it helps to reduce test dependencies.
  12 6. Avoid noise-words in variable names, like 'data' or 'info'.  Think about what you're naming and name it well.  Don't be afraid to rename anything.
  13 7. Avoid comments that describe what the code is doing, the code should describe itself.  Comments are useful however for big-picture purposes and to document content of variables.
  14 8. If you need to document a variable do it at the declaration, don't copy the comment to the `extern` usage since it will lead to comment rot.
  15 9. Seek advice from other developers - know you can always learn more.
  16 10. Be professional - attempts at humor or slating existing code in the codebase itself is not helpful when you have to change/fix it.
  17 11. Know that there's always more than one way to do something and that code is never final - but it does have to work.
  18
  19 Before making any code contributions, try to comply with the [coding style](CodingStyle.md). It has a lot of sound advice.
  20
  21 It is also advised to read about clean code, here are some useful links:
  22
  23 * http://cleancoders.com/
  24 * http://en.wikipedia.org/wiki/SOLID_%28object-oriented_design%29
  25 * http://en.wikipedia.org/wiki/Code_smell
  26 * http://en.wikipedia.org/wiki/Code_refactoring
  27 * http://www.amazon.co.uk/Working-Effectively-Legacy-Robert-Martin/dp/0131177052
  28
  29 ## Unit testing
  30
  31 Ideally, there should be tests for any new code. However, since this is a legacy codebase which was not designed to be tested this might be a bit difficult.
  32
  33 If you want to make changes and want to make sure it's tested then focus on the minimal set of changes required to add a test.
  34
  35 Tests currently live in the `test` folder and they use the google test framework.
  36 The tests are compiled and run natively on your development machine and not on the target platform.
  37 This allows you to develop tests and code and actually execute it to make sure it works without needing a development board or simulator.
  38
  39 This project could really do with some functional tests which test the behaviour of the application.
  40
  41 All pull requests to add/improve the testability of the code or testing methods are highly sought!
  42
  43 Note: Tests are written in C++ and linked with with firmware's C code. All code is also instrumented using gcov to make test coverage analysis possible.
  44
  45 ### Running the tests.
  46
  47 The tests and test build system is very simple and based off the googletest example files, it will be improved in due course. From the root folder of the project simply do:
  48
  49 ```
  50 make test
  51 ```
  52
  53 You can also do:
  54
  55 ```
  56 make junittest
  57 ```
  58
  59 This will build a set of executable files in the `obj/test` folder, one for each `*_unittest.cc` file.
  60 It will stop after first compile/build error. If you want it to continue with the next test module you can use `make -k test`.
  61
  62 After they have been executed by the make invocation, you can still run them on the command line to execute the tests and to see the test report. Test reports will also be produced in form of junit XML files, if tests are built and run with the "junittest" goal. Junit report files are saved in obj/test directory and has the following  naming pattern test_name_results.xml, for example: obj/test/battery_unittest_results.xml
  63
  64 You can also step-debug the tests in eclipse and you can use the GoogleTest test runner to make building and re-running the tests simple.
  65
  66 The tests are currently always compiled with debugging information enabled, there may be additional warnings, if you see any warnings please attempt to fix them and submit pull requests with the fixes.
  67
  68 Tests are verified and working with GCC 4.9.3
  69
  70 ## Test coverage analysis
  71
  72 There are a number of possibilities to analyse test coverage and produce various reports. There are guides available from many sources, a good overview and link collection to more info can be found on Wikipedia:
  73
  74 https://en.wikipedia.org/wiki/Gcov
  75
  76 A simple report for a single test can for example be made using this command:
  77
  78 ```
  79 gcov -s src/main/sensors -o obj/test/ battery_unittest.cc
  80 ```
  81
  82 To produce an coverage report in xml format usable by the Cobertura plugin in Jenkins requires installation of a  Python script called "gcovr" from github:
  83
  84 https://github.com/gcovr/gcovr/tree/dev
  85
  86 Example usage in Jenkins:
  87
  88 ```
  89 /gcovr-install-path/gcovr/scripts/gcovr obj/test --root=src/main -x > coverage.xml
  90 ```
  91
  92 There are many other ways to prodice test coverage reports in other formats, like html etc etc.
  93
  94 ## Using git and github
  95
  96 Ensure you understand the github workflow: https://guides.github.com/introduction/flow/index.html
  97
  98 Please keep pull requests focused on one thing only, since this makes it easier to merge and test in a timely manner.
  99
 100 If you need help with pull requests there are guides on github here:
 101
 102 https://help.github.com/articles/creating-a-pull-request/
 103
 104 The main flow for a contributing is as follows:
 105
 106 1. Login to github, go to the u360gts repository and press `fork`.
 107 2. Then using the command line/terminal on your computer: `git clone <url to YOUR fork>`
 108 3. `cd u360gts`
 109 4. `git checkout master`
 110 5. `git checkout -b my-new-code`
 111 6. Make changes
 112 7. `git add <files that have changed>`
 113 8. `git commit`
 114 9. `git push origin my-new-code`
 115 10. Create pull request using github UI to merge your changes from your new branch into `u360gts/master`
 116 11. Repeat from step 4 for new other changes.
 117
 118 The primary thing to remember is that separate pull requests should be created for separate branches.  Never create a pull request from your `master` branch.
 119
 120 Once you have created the PR,
 121 every new commit/push in your branch will propagate from your fork into the PR in the main github/u360gts repo.
 122 Checkout another branch first if you want something else.
 123
 124 Push will often fail if you edit or squash commits in a branch already pushed. Never do such things after creating the PR.
 125
 126 Later, you can get the changes from the u360gts repo into your `master` branch by adding u360gts as a git remote and merging from it as follows:
 127
 128 1. `git remote add u360gts https://github.com/u360gts/u360gts.git`
 129 2. `git checkout master`
 130 3. `git fetch u360gts`
 131 4. `git merge u360gts/master`
 132 5. `git push origin master` is an optional step that will update your fork on github
 133
 134
 135 You can also perform the git commands using the git client inside Eclipse.  Refer to the Eclipse git manual.
 136
 137