Feedback from PR. Related to #3671

* Defensive Programming
* Doc convention
* Explicit return types