|
|
# Coding standards
|
|
|
|
|
|
**1. Word separation**
|
|
|
**Code Style**
|
|
|
|
|
|
* Seperate words with _
|
|
|
We have a .pylintrc config file in the repository use it.
|
|
|
|
|
|
**2. Widget variables**
|
|
|
**Variable and method names**
|
|
|
|
|
|
Widget names are all lower-case and the last word should be the widget type:
|
|
|
* **Dont** use CamelCase for variables and method names
|
|
|
|
|
|
* jid_comboboxentry
|
|
|
* chat_button
|
|
|
* new_message_menuitem
|
|
|
|
|
|
**3. Callbacks**
|
|
|
**Callbacks**
|
|
|
|
|
|
The default style is used, so we have:
|
|
|
|
... | ... | @@ -25,29 +21,23 @@ The arguments in the the callbacks (and in the .connect()s) have this sequence o |
|
|
# notice we start from ACCOUNT ending up in contact.
|
|
|
foo.connect('clicked', on_foo_clicked, account, group, contact)
|
|
|
|
|
|
**4. Classes**
|
|
|
|
|
|
The first letter must be **C**apital and if a class has to do with widgets, the last word should be the widget type it creates/handles.
|
|
|
**Classes**
|
|
|
|
|
|
* class ChatWindow
|
|
|
* class User
|
|
|
We use CamelCase for Classes
|
|
|
|
|
|
|
|
|
**5. UI**
|
|
|
**UI**
|
|
|
|
|
|
See: [Gnome guidelines on how to design UIs](https://developer.gnome.org/hig/stable/).
|
|
|
|
|
|
NOTE: The point is for the widgets to look nice in an objective way, and to be aligned well.
|
|
|
Most windows/dialogs that have many children have borders with width 12 (else 6), and most GTK boxes have a spacing of 6. In tables, horizontal spacing is set to 12 and vertical spacing to 6. In general the widgets you draw should look nice, so have a look at the glade file to see already implemented windows/dialogs. We write hints like 'Enter password:' in labels or where it's needed. Notice that we use ':' and we don't have a space before.
|
|
|
|
|
|
We use .show() / .hide() for windows/dialogs most of the times. See [show/destroy](./DevShowDestroy) for more. We use mostly dialogs because they are more handy (ESC works out of the box, etc.), and they look nicer.
|
|
|
Most windows/dialogs that have many children have borders with width 12 (else 6), and most GTK boxes have a spacing of 6. In tables, horizontal spacing is set to 12 and vertical spacing to 6. In general the widgets you draw should look nice, so have a look at the glade file to see already implemented windows/dialogs.
|
|
|
|
|
|
**6. Tabulations**
|
|
|
**Tabulations**
|
|
|
|
|
|
~~We use tabs and not spaces. Tab width is 3.~~
|
|
|
We use spaces not tabs. We use 4 spaces to indent.
|
|
|
|
|
|
**7. Write clean, readable, optimized pythonic code**
|
|
|
**Write clean, readable, optimized pythonic code**
|
|
|
|
|
|
You can always consult the [PEP 8 python style guide](https://www.python.org/dev/peps/pep-0008/).
|
|
|
|
... | ... | @@ -55,26 +45,13 @@ We love Python and we try to write the pythonic way, therefore: |
|
|
* Read [Python Performance Tips](https://wiki.python.org/moin/PythonSpeed/PerformanceTips) and [PythonSpeed](https://wiki.python.org/moin/PythonSpeed)
|
|
|
* Use !True/False instead of 1 and 0
|
|
|
* Use single quotes (' ') not double quotes (" ")
|
|
|
* Keep the 80 chars right margin; use '\ ' when necessary, (for example long ifs with in/and/or)
|
|
|
* Keep the 80 chars right margin
|
|
|
* Use value = model[iter][0] not value = model.get_value(iter, 0)
|
|
|
* Use xrange() instead of range() and use tuples () instead of lists [] for looping in and/or checking 'if foo in', both assure optimized code
|
|
|
* Write isinstance(a, dict) instead of type(a) == type({}) as it is faster
|
|
|
* Readability comes first and only after readability comes code optimization
|
|
|
|
|
|
**8. Spacing**
|
|
|
|
|
|
Put spaces around binary operators such as = == != + - / * etc. Unary operators get no space.
|
|
|
Also no space around . attribute/method addressing operator or around ( and ).
|
|
|
No space before, and one space after commas. No surprises here.
|
|
|
|
|
|
Exception: When defining or invoking named function parameters, use no space around =. For example:
|
|
|
|
|
|
def myblahfunc(myparm=None):
|
|
|
and:
|
|
|
|
|
|
a = myblahfunc(myparm='hello')
|
|
|
|
|
|
**9. Comments**
|
|
|
**Comments**
|
|
|
|
|
|
Comments for developers MUST be in the form
|
|
|
|
... | ... | @@ -86,12 +63,12 @@ Comments for translators MUST be in the form |
|
|
|
|
|
Documentation style has to follow [PEP 287](http://www.python.org/dev/peps/pep-0287/) and is using [reST markup](http://epydoc.sourceforge.net/othermarkup.html)
|
|
|
|
|
|
**10. Write good strings**
|
|
|
**Write good strings**
|
|
|
|
|
|
Write good English strings (easy to understand, without typos, correct syntax). Your strings should follow [Layout GNOME Hig Rules](https://developer.gnome.org/hig/stable/visual-layout.html) and 'primary text has puncation only if ? so not . in primary text. In secondary always put .'
|
|
|
'As HIG says, alert dialogs don't have titles, etc.' READ THE HIG.
|
|
|
|
|
|
**11. Using %s %d and not + for strings**
|
|
|
**Using %s %d and not + for strings**
|
|
|
|
|
|
Using %s %d and not + for strings that the user sees or has chances to see in the future and being translation friendly.
|
|
|
|
... | ... | @@ -116,38 +93,7 @@ People talk hundreds of languages, keep that in mind and follow this example: |
|
|
#eg. OS can be feminine and Client can be masculine. and Unknown adjective can differ between feminine and masculine
|
|
|
|
|
|
|
|
|
**12. Use unicode strings wherever possible**
|
|
|
|
|
|
We use unicode strings everywhere, but there's a couple of places to make sure you're actually using them as well:
|
|
|
|
|
|
* Whenever you read from a file, you get a regular string. You can use the .decode string method aswell, but there's no way of telling what encoding the file is using! UTF-8 is generally a good default though.
|
|
|
* Whenever you write to a file, encode the unicode string back to a utf-8 string, or you'll get exceptions:
|
|
|
`some_file.write(my_string.encode('utf-8'))`
|
|
|
|
|
|
|
|
|
**13. Alignment when breaking to avoid more than 80 chars in a line**
|
|
|
|
|
|
We write:
|
|
|
|
|
|
if foooooooooooooooooooooooooooooooooooooooooooo and\
|
|
|
bar:
|
|
|
print 'yes indeed'
|
|
|
|
|
|
When we call functions/methods we do:
|
|
|
|
|
|
boo = do_this_and_that(one, two, three, four,
|
|
|
five, six)
|
|
|
|
|
|
When we define functions/methods we do:
|
|
|
|
|
|
def foo(abc, doremi,
|
|
|
lalallala):
|
|
|
print abc
|
|
|
|
|
|
Generally, next line after *:* has to be visually easy to find (indented).
|
|
|
|
|
|
|
|
|
**14. Vim modelines**
|
|
|
**Vim modelines**
|
|
|
|
|
|
Here are some settings for your .vimrc that will help you follow the Gajim coding standards. In this example, all the Gajim source is found in a directory that matches the pattern: "/home/travis/devel/gajim-*/*".
|
|
|
|
... | ... | |