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
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ Plasma-devel mailing list Plasma-devel@kde.org https://mail.kde.org/mailman/listinfo/plasma-devel
