[libcamera-devel] Documentation: Adjust guidelines regarding math.h header

9674 diff mbox series

While libcamera prefers usage of the C standard library headers (xxx.h)
over the C++ version (cxxx), we make an exception for cmath as the
overloaded versions of the math functions are convenient. Document this,
and adjust checkstyle.py accordingly.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 Documentation/coding-style.rst | 14 +++++++++++---
 utils/checkstyle.py            |  6 +++---
 2 files changed, 14 insertions(+), 6 deletions(-)

Jacopo, this originates from a discussion in the review of "[PATCH]
libcamera: ipu3: Fix compilation issues with gcc5". I haven't assigned
the authorship to you as you didn't provide a formal patch with an SoB
line. Please let me know if I should (and give me your SoB in that
case). Otherwise, a review is always appreciated :-)

Hi Laurent,

On Sun, Sep 20, 2020 at 08:34:47PM +0300, Laurent Pinchart wrote:
> While libcamera prefers usage of the C standard library headers (xxx.h)
> over the C++ version (cxxx), we make an exception for cmath as the
> overloaded versions of the math functions are convenient. Document this,
> and adjust checkstyle.py accordingly.
>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
>  Documentation/coding-style.rst | 14 +++++++++++---
>  utils/checkstyle.py            |  6 +++---
>  2 files changed, 14 insertions(+), 6 deletions(-)
>
> Jacopo, this originates from a discussion in the review of "[PATCH]
> libcamera: ipu3: Fix compilation issues with gcc5". I haven't assigned
> the authorship to you as you didn't provide a formal patch with an SoB
> line. Please let me know if I should (and give me your SoB in that
> case). Otherwise, a review is always appreciated :-)

Did I send a patch for this ? Or was just a suggestion made during
review ? I think a r-b tag is enough, no worries..

>
> diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
> index 7c56a1b70014..d467a5a1b1ad 100644
> --- a/Documentation/coding-style.rst
> +++ b/Documentation/coding-style.rst
> @@ -195,9 +195,17 @@ them, defines C compatibility headers. The former have a name of the form
>  <cxxx> while the later are named <xxx.h>. The C++ headers declare names in the
>  std namespace, and may declare the same names in the global namespace. The C
>  compatibility headers declare names in the global namespace, and may declare
> -the same names in the std namespace. Usage of the C compatibility headers is
> -strongly preferred. Code shall not rely on the optional declaration of names in
> -the global or std namespace.
> +the same names in the std namespace. Code shall not rely on the optional
> +declaration of names in the global or std namespace.
> +
> +Usage of the C compatibility headers is preferred, except for the math.h header.
> +Where math.h defines separate functions for different argument types (e.g.
> +abs(int), labs(long int), fabs(double) and fabsf(float)) and requires the
> +developer to pick the right function, cmath defines overloaded functions
> +(std::abs(int), std::abs(long int), std::abs(double) and std::abs(float) and let

"and let" seems to refer to "cmath" as a suject, so it's either "lets"
or "to let" ?

> +the compiler select the right function. This avoids potential errors such as
> +calling abs(int) with a float argument, performing an unwanted implicit integer
> +conversion. For this reason, cmath is preferred over math.h.

Looks good, sorry I forgot about this.

Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>

Thanks
  j

>
>
>  Documentation
> diff --git a/utils/checkstyle.py b/utils/checkstyle.py
> index b594a19aed5b..d5dc26c0f666 100755
> --- a/utils/checkstyle.py
> +++ b/utils/checkstyle.py
> @@ -244,9 +244,9 @@ class IncludeChecker(StyleChecker):
>      patterns = ('*.cpp', '*.h')
>
>      headers = ('assert', 'ctype', 'errno', 'fenv', 'float', 'inttypes',
> -               'limits', 'locale', 'math', 'setjmp', 'signal', 'stdarg',
> -               'stddef', 'stdint', 'stdio', 'stdlib', 'string', 'time', 'uchar',
> -               'wchar', 'wctype')
> +               'limits', 'locale', 'setjmp', 'signal', 'stdarg', 'stddef',
> +               'stdint', 'stdio', 'stdlib', 'string', 'time', 'uchar', 'wchar',
> +               'wctype')
>      include_regex = re.compile('^#include <c([a-z]*)>')
>
>      def __init__(self, content):
> --
> Regards,
>
> Laurent Pinchart
>

Hi Laurent,

Thanks for your work.

On 2020-09-20 20:34:47 +0300, Laurent Pinchart wrote:
> While libcamera prefers usage of the C standard library headers (xxx.h)
> over the C++ version (cxxx), we make an exception for cmath as the
> overloaded versions of the math functions are convenient. Document this,
> and adjust checkstyle.py accordingly.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>

> ---
>  Documentation/coding-style.rst | 14 +++++++++++---
>  utils/checkstyle.py            |  6 +++---
>  2 files changed, 14 insertions(+), 6 deletions(-)
> 
> Jacopo, this originates from a discussion in the review of "[PATCH]
> libcamera: ipu3: Fix compilation issues with gcc5". I haven't assigned
> the authorship to you as you didn't provide a formal patch with an SoB
> line. Please let me know if I should (and give me your SoB in that
> case). Otherwise, a review is always appreciated :-)
> 
> diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
> index 7c56a1b70014..d467a5a1b1ad 100644
> --- a/Documentation/coding-style.rst
> +++ b/Documentation/coding-style.rst
> @@ -195,9 +195,17 @@ them, defines C compatibility headers. The former have a name of the form
>  <cxxx> while the later are named <xxx.h>. The C++ headers declare names in the
>  std namespace, and may declare the same names in the global namespace. The C
>  compatibility headers declare names in the global namespace, and may declare
> -the same names in the std namespace. Usage of the C compatibility headers is
> -strongly preferred. Code shall not rely on the optional declaration of names in
> -the global or std namespace.
> +the same names in the std namespace. Code shall not rely on the optional
> +declaration of names in the global or std namespace.
> +
> +Usage of the C compatibility headers is preferred, except for the math.h header.
> +Where math.h defines separate functions for different argument types (e.g.
> +abs(int), labs(long int), fabs(double) and fabsf(float)) and requires the
> +developer to pick the right function, cmath defines overloaded functions
> +(std::abs(int), std::abs(long int), std::abs(double) and std::abs(float) and let
> +the compiler select the right function. This avoids potential errors such as
> +calling abs(int) with a float argument, performing an unwanted implicit integer
> +conversion. For this reason, cmath is preferred over math.h.
>  
>  
>  Documentation
> diff --git a/utils/checkstyle.py b/utils/checkstyle.py
> index b594a19aed5b..d5dc26c0f666 100755
> --- a/utils/checkstyle.py
> +++ b/utils/checkstyle.py
> @@ -244,9 +244,9 @@ class IncludeChecker(StyleChecker):
>      patterns = ('*.cpp', '*.h')
>  
>      headers = ('assert', 'ctype', 'errno', 'fenv', 'float', 'inttypes',
> -               'limits', 'locale', 'math', 'setjmp', 'signal', 'stdarg',
> -               'stddef', 'stdint', 'stdio', 'stdlib', 'string', 'time', 'uchar',
> -               'wchar', 'wctype')
> +               'limits', 'locale', 'setjmp', 'signal', 'stdarg', 'stddef',
> +               'stdint', 'stdio', 'stdlib', 'string', 'time', 'uchar', 'wchar',
> +               'wctype')
>      include_regex = re.compile('^#include <c([a-z]*)>')
>  
>      def __init__(self, content):
> -- 
> Regards,
> 
> Laurent Pinchart
> 
> _______________________________________________
> libcamera-devel mailing list
> libcamera-devel@lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel

Hi Jacopo,

On Mon, Sep 21, 2020 at 09:43:03AM +0200, Jacopo Mondi wrote:
> On Sun, Sep 20, 2020 at 08:34:47PM +0300, Laurent Pinchart wrote:
> > While libcamera prefers usage of the C standard library headers (xxx.h)
> > over the C++ version (cxxx), we make an exception for cmath as the
> > overloaded versions of the math functions are convenient. Document this,
> > and adjust checkstyle.py accordingly.
> >
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> >  Documentation/coding-style.rst | 14 +++++++++++---
> >  utils/checkstyle.py            |  6 +++---
> >  2 files changed, 14 insertions(+), 6 deletions(-)
> >
> > Jacopo, this originates from a discussion in the review of "[PATCH]
> > libcamera: ipu3: Fix compilation issues with gcc5". I haven't assigned
> > the authorship to you as you didn't provide a formal patch with an SoB
> > line. Please let me know if I should (and give me your SoB in that
> > case). Otherwise, a review is always appreciated :-)
> 
> Did I send a patch for this ? Or was just a suggestion made during
> review ? I think a r-b tag is enough, no worries..

You've provided an initial diff proposal in a review reply, and we
discussed it a bit.

> > diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
> > index 7c56a1b70014..d467a5a1b1ad 100644
> > --- a/Documentation/coding-style.rst
> > +++ b/Documentation/coding-style.rst
> > @@ -195,9 +195,17 @@ them, defines C compatibility headers. The former have a name of the form
> >  <cxxx> while the later are named <xxx.h>. The C++ headers declare names in the
> >  std namespace, and may declare the same names in the global namespace. The C
> >  compatibility headers declare names in the global namespace, and may declare
> > -the same names in the std namespace. Usage of the C compatibility headers is
> > -strongly preferred. Code shall not rely on the optional declaration of names in
> > -the global or std namespace.
> > +the same names in the std namespace. Code shall not rely on the optional
> > +declaration of names in the global or std namespace.
> > +
> > +Usage of the C compatibility headers is preferred, except for the math.h header.
> > +Where math.h defines separate functions for different argument types (e.g.
> > +abs(int), labs(long int), fabs(double) and fabsf(float)) and requires the
> > +developer to pick the right function, cmath defines overloaded functions
> > +(std::abs(int), std::abs(long int), std::abs(double) and std::abs(float) and let
> 
> "and let" seems to refer to "cmath" as a suject, so it's either "lets"
> or "to let" ?

Good catch, I'll fix it.

> > +the compiler select the right function. This avoids potential errors such as
> > +calling abs(int) with a float argument, performing an unwanted implicit integer
> > +conversion. For this reason, cmath is preferred over math.h.
> 
> Looks good, sorry I forgot about this.

No worries :-)

> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
> 
> >  Documentation
> > diff --git a/utils/checkstyle.py b/utils/checkstyle.py
> > index b594a19aed5b..d5dc26c0f666 100755
> > --- a/utils/checkstyle.py
> > +++ b/utils/checkstyle.py
> > @@ -244,9 +244,9 @@ class IncludeChecker(StyleChecker):
> >      patterns = ('*.cpp', '*.h')
> >
> >      headers = ('assert', 'ctype', 'errno', 'fenv', 'float', 'inttypes',
> > -               'limits', 'locale', 'math', 'setjmp', 'signal', 'stdarg',
> > -               'stddef', 'stdint', 'stdio', 'stdlib', 'string', 'time', 'uchar',
> > -               'wchar', 'wctype')
> > +               'limits', 'locale', 'setjmp', 'signal', 'stdarg', 'stddef',
> > +               'stdint', 'stdio', 'stdlib', 'string', 'time', 'uchar', 'wchar',
> > +               'wctype')
> >      include_regex = re.compile('^#include <c([a-z]*)>')
> >
> >      def __init__(self, content):