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

[Luigi Pirelli]

On 6 October 2016 at 00:29, Nyall Dawson <nyall.dawson at gmail.com> wrote:
> First issue: with doxygen comments, do we go:
>
> 1.
>
> /**
>  * my awesome function
>  * does something cool
>  */
>
> or
>
> 2.
>
> /** my awesome function
>  * does something cool
>  */

+1 for option 1) (with strk proposal)

> 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"

+1 for option 1)

> and does this apply to both the descriptions AND extra tags like
> notes? Or do different rules apply?

both for consistency

> 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 vote for self explanatory var names and less time spent documenting
obvious stuffs.
Btw if a param description is necessary... to leave doxy quite, add
the description for all.
I don't remember many cases where vars names does not explain their meaning.
If a var has a polysemantic meaning, probably the api have to be redefined.

> That is all
>
> Nyall

cheers

Luigi Pirelli

**************************************************************************************************
* Boundless QGIS Support/Development: lpirelli AT boundlessgeo DOT com
* LinkedIn: https://www.linkedin.com/in/luigipirelli
* Stackexchange: http://gis.stackexchange.com/users/19667/luigi-pirelli
* GitHub: https://github.com/luipir
* Mastering QGIS:
https://www.packtpub.com/application-development/mastering-qgis
**************************************************************************************************