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

[Sandro Santilli]

My 2 eurocents....

On Thu, Oct 06, 2016 at 08:29:36AM +1000, Nyall Dawson wrote:

> First issue: with doxygen comments, do we go:
> 
> 1.
> 
> /**
>  * my awesome function
>  * does something cool
>  */
> 
> or
> 
> 2.
> 
> /** my awesome function
>  * does something cool
>  */

In GEOS, I've learnt to leave a blank space between the short
description and the long description, which each have a role
and can alternatively been marked with \brief and dunno which other
tage (in GEOS the Doxygen configuration accepts the blank line).

So, assuming the QGIS Doxygen configuration does the same,
it would be:

/**
 * My awesome function
 *
 * Does something cool
 * 
 */


> Second issue: do we
> 
> 1. Write in full sentences, with initial caps + trailing "." eg "Does
> something cool to QGIS."
> 
> or
> 
> 2. Use fragments, with no caps or ".", eg "does something cool"
> 
> and does this apply to both the descriptions AND extra tags like
> notes? Or do different rules apply?

No preferences here for me.

> 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 tend to only document non-trivial params too, but if that makes
doxygen raise lots of warning it's worth reducing them.

--strk;