Justification

Enough information should be provided by the function header to help the reader to use the function without the necessity of reading the implementation of the function and to help the reviewer to verify whether the function has correctly been coded.

Example

/*----------------------------------------------------------------------------*/
int get_maintenance_status(
    FIRST_MAINTENANCE_STRUCT *first_maintenance,
    MAINTENACE_STATUST_STRUCT *maintenance_status,
    const SHARED_DATE_STRUCT *sh_data)
/**
 * \brief Returns the time to the next maintenance action
 * \param[in] sh_data  The shared data structure
 * \param[out] first_maintenance  Indication when first maintenance is required
 * \param[out] maintenance_status  Indication time to go before maintenance
 * \return error status  OK, SYS_ERR
 * \retval  {description}
 * \pre None
 * \post first_maintenance
 *       maintenance_status 
 *       - Initialised with zeroes
 * \note The precondition implies that this is a maintenance object.
 */
{
   /* Function definition */
}