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

[Nyall Dawson]

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

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