AnsweredAssumed Answered

response to "HAL Code Quality"

Question asked by robitzki.torsten on Jul 14, 2016
Hello Mayla,
here are some examples:


*  If there is a function that can not fail, please use void as return type:

„HAL_StatusTypeDef HAL_DeInit(void)" should be „void HAL_DeInit(void)“. If the software does not contain any bugs, there is usually nothing that can fail, when you destruct things. If we would call HAL_DeInit() during shutdown, how should / could an error reported by HAL_DeInit() being handled? Don’t get me wrong, I don’t say, rewrite every function that currently just return HAL_OK into a function with void as return type. But if we have functions that, from their nature can not fail, we shouldn’t have an error code return type.

* If a function can fail, please document under which circumstances the function will return which error code.

Most functions return value is documented with „@retval HAL status“, which is of little value. Just grep for „@retval HAL status“.

* If a function can only fail if used not correctly (is called with not given precondition, wrong state, wrong parameters), please do the assert() for us and change the return type to void.

„HAL_StatusTypeDef HAL_DMA_Init(DMA_HandleTypeDef *hdma)“ documents the return value with „HAL status“. It just fails when the given hdma parameter is 0. So this function can not fail if the required preconditions are given. Just assert that hdma is not 0 and change the return type to void. In other parts of the HAL, there is function assert_param() used. HAL_DMA_Init() is also a good example for a function that can not fail, as it just initiates a C struct.

* Please, if a called function returns an error, promote that error to the caller and do not simply swallow it.

USB_CoreInit() for example calls USB_CoreReset(), which has a HAL_StatusTypeDef as return types that is ignored.


kind regards

Torsten

I was unable to reply in the thread, as the forum software always complain about "page not found"

Outcomes