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

[Nyall Dawson]

On 6 October 2016 at 08:51, Matthias Kuhn <matthias at opengis.ch> wrote:
> 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.

Do you mean #1 here?
https://github.com/qgis/QGIS/commit/b642c3ff5ede2cae88d30f881f7ae7c99e1bfccc#diff-aaa596c71ada12dd18c410856a8f4f77R64
would lead me to think you prefer that style?

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

Agree - BUT doxygen doesn't allow this and will throw a warning. So
for any method with at least one parameter which needs useful docs it
requires all parameters to be documented. One solution could be to
just go:

/**
 *  My function.
 * @param color
 * @param size
 * @param p magic number. If p > 5 then qgis will run faster, if p = 5
then qgis 2.0 api will be used, if p< 5 then output will be scaled to
painter's dpi.
 */

Ie put the @param's for obvious parameters to keep doxygen happy but
leave them empty. That would help draw attention to important
parameters.

Nyall

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