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

Stéphane Brunner stephane.brunner at camptocamp.com
Thu Oct 6 23:29:57 PDT 2016


Hello,

2016-10-06 0:29 GMT+02:00 Nyall Dawson <nyall.dawson at gmail.com>:

> 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
>  */
>

+1 for the first, more readable :-)

CU
Stéphane



>
> 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?
>
>
> 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...
>
>
> That is all
>
> Nyall
> _______________________________________________
> Qgis-developer mailing list
> Qgis-developer at lists.osgeo.org
> List info: http://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: http://lists.osgeo.org/mailman/listinfo/qgis-developer




-- 
camptocamp.com
mapfish.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20161007/25a500a4/attachment.html>


More information about the Qgis-developer mailing list