QML style guide

[Aaron J. Seigo]

On Tuesday, October 30, 2012 12:25:14 Dmitry Ashkadov wrote: 
> First of all, it a good idea!

:)

> 1. I think you should explain why you have chosen  such style instead of
> another one. Your decision should be justified. 

this is the death of style guides. for many style decisions there is no 
justification that can be made; it is simply a matter of custom and personal 
taste. tabs vs spaces is the classic example.

we just need to accept that some style guide decisions will be arbitrary and 
not worry too much about it. the goal is a consistent and predictable code 
base, not a perfect style guide.

> For example: I don't
> understand why you put brace on new line in case of function. As for me

this one i can at least explain, though :) 

it is how we do it in all our non-QML code (e.g. C++). in .js files, i want the 
code to be formatted as close to how we write code in other languages as 
reasonable, which means:

function foo()
{
}

fair enough, right? this is "obvious" for .js files, but what about JS 
functions in QML files? 

the guide i followed was therefore this:

* if it is a QML "identifer:" line, do it "QML style" which is brace-on-same-
line like we do for if/when/else etc (for better or worse, i don't really care 
:)

* if it is straight, plain JS then follow the kdelibs style we use everywhere 
else. and that means function braces on their own line.

does this matter in our QML code? yes. in the same files i saw both:

function foo() {
}

and 

function bar()
{
}

horrible.

> it's terrible because I need always remember that there is one exception
> for function definition and every time check functions. It's easier

you'll get used to it. i got used to the kdelibs style even though it differed 
from my preferences at the time.

> 2. Why you put JS into code directory? 

for the same reason we have an images/, config/ and ui/ directories.

it is not only a cleaner layout with actual organization, it makes it easier 
to use plasmate (and similar apps) as everything has a well-defined home.

plasmate puts all code in code/ and QML in ui/. that's how the plasmoid 
package is defined, in fact.

> IMHO, import "../../code/.."
> looks awfully. 

this is because there is no way to influence how import lines work at runtime. 
it's a failing of QML (or, rather, of the people who implemented it). it makes 
this a bit (though not much) uglier, but more importantly this is also a 
security hole.

oh, and it actually is:

import "../code/foo.js"

just one "../" and i don't think that's overly ugly at all.

> Some JS can be an adjunct to QML file and cannot be used
> outside of this QML file. Such JS can provide stuff for only one QML. To

should each QML file go into its own directory?

contents/main/main.qml
contents/main/main.js
contents/itemdelegate/delegate.qml
contents/itemdelegate/delegate.js

if we accept that "code should be kept with its QML it is used by" then we 
quite quickly come to "so separate all the qml based on what qml uses what 
js". it's nonesense :)

> simplify understanding such situation such JS and QML files may be named
> similar:  main.js & main.qml. And it may be better to put them into the
> same directory.

i disagree. it's how we've been doing Plasma::Packages from the start, and for 
good reasons (e.g. plasmate). people writing QML packages failed to appreciate 
those reasons, fair enough, but those reasons still exist, are valid and will 
be how we continue to work.

> 3. What is better:

imho this will vary from use-case to use-case.

> Q: who is responsible to set geometry properties: parent or child ?
> I think, parent.

it's probably the most common case, and perhaps even a best practice. i don't 
think it will *always* be the case, however, so i don't want to make it a 
guideline.

after we have the basic style guide to where we want it, then lets add a 'best 
practices' guide and this can go there.

> 4. What is about private functions? What is about private properties?
> Should they go first or last in QML files? Should they have special naming?

"private" is not a concept found in QML/JS. the suggestion here:

http://doc.qt.digia.com/qt/qml-coding-conventions.html#private-properties

is to preface with "__", but imho that's simply non-sense as it gives a false 
sense of security/cleanliness. the only benefit is that it becomes easier to 
grep for "__" to find supposedly-private properties.

if a QML item is meant to be used outside of its own package (so that it is 
"public API") all of its publicly usable properties should be documented with 
apidox. if it is not documented, it isn't public. period. no meaningless 
naming sugar.

if a QML item is only to be used internally, there's no material benefit to 
marking private vs non-private (again, because QML/JS has no such concept)

> 5. Vim:
> > The {{{ and }}} are just for the sakes of vim's automatic folding.
> 
> Do we all use vim? I think no. So, we must never force developers use vim.

i mostly agree :) i don't think this forces anyone to use vim, but i would 
like to see a solution that works with katepart before adding it to the style 
guide.
 
> 6.
> 
> > i'm ok either way, but declared properties before geometry properties
> > means we need to alter nearly every single QML file to meet that
> > guideline.
> Let them be unchanged until somebody want to do it. Old code will always
> stop you to make new code better. Refuse new code made in old style.

so your vote is to live with it being inconsistent for now, and in new code 
put geometry properties with the other inhereted properties, correct?

-- 
Aaron J. Seigo
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/plasma-devel/attachments/20121030/d6748a2b/attachment.sig>