[Qgis-developer] VERY important discussion re QGIS coding standards

[Martin Dobias]

Hi Nyall

On Thu, Oct 6, 2016 at 6:29 AM, Nyall Dawson <nyall.dawson at gmail.com> wrote:
> Pretty sure I'm not the only OCD member of the QGIS team who hates
> inconsistency and is affected by these issues ;)
>
> First issue: with doxygen comments, do we go:
>
> 1.
>
> /**
>  * my awesome function
>  * does something cool
>  */
>
> or
>
> 2.
>
> /** my awesome function
>  * does something cool
>  */

The first one has a nice symmetry, the second one is more compact... I
am fine with either.


> Second issue: do we
>
> 1. Write in full sentences, with initial caps + trailing "." eg "Does
> something cool to QGIS."

+1 for this option.


> Third issue:
>
> Do we document parameters? I've been doing this because doxygen
> requires an "all or nothing" approach, eg you can't only document the
> tricky parameters and leave obvious ones out. This ends up in a lot of
> obvious "@param fillColor new fill color" type docs, which seem
> redundant. I generally do this so that the occasional trickier
> parameter is easier to document (eg "@param symbol new symbol style
> for fill, ownership is transferred to the renderer"). But I often
> wonder if everyone is wondering what the heck I'm doing writing docs
> like "@param width new width", so I'm curious to hear other
> opinions...

I am very much in favor of not having the @param tags in the docs...
in most of the cases the meaning of parameters is very obvious, for
the less obvious ones I would mention them in the method documentation
and explain them in further detail... just like in Qt docs, which
seems to work pretty well. Python docs also do not come with a table
of parameters, they rather explain those in text.

Cheers
Martin