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

[Matthias Kuhn]

I've been thinking about the same. And have some opinions.

On 06/10/16 00:29, Nyall Dawson 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
>  */
My vote clearly goes to #2.

The reason is that it adds additional space between one method and the
comment of the next method (which are logically different parts).
This helps (me) to be able scroll through headers quicker and still spot
method names.

+1 to 2.

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

The advantage of full sentences is, that they always work and can be
used consistently. And a quick look at the Qt docs shows that they seem
to be doing the same.

+0 on 1.

> 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 like self-explanatory names and I don't like stating the obvious.
Therefore I'm rather in the camp "if a parameter name is intuitive, I
don't want to spend some of my attention and screen space on parsing
useless documentation for it".

I don't have a problem with only including params where there is useful
additional info (also if 4 of these 5 parameters are not of this kind),
same for return. Documenting parameters for setters and return values
for getters is mostly redundant.

But I can totally understand if someone once to keep this consistent.

Matthias

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