rnhmjoj/qutebrowser
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update HACKING

Browse Source
This commit is contained in:
Florian Bruhin 2014-06-18 20:35:08 +02:00
parent 36d31efe13
commit d18f02cc7a
1 changed files with 107 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

172
HACKING
View File

@ -1,79 +1,128 @@
== Use the scripts! == qutebrowser HACKING
===================
In the scripts/ subfolder, there are a run_checks.py and a run_profile.py. Run checks!
-----------
run_checks runs the flake8/pylint/pep257 checkers on all source files. Please In the _scripts/_ subfolder, there are a `run_checks.py`.
makes this script complete without any messages with your patch. There are some
techniques to handle "wrong" error messages:
- Use _foo for unused parameters (not '_') `run_checks.py` runs a bunch of static checks on all source files. It uses the
following checkers to do so:
- If you think you have a good reason to suppress a message, use: * unittests using the Python
# pylint: disable=message-name https://docs.python.org/3.4/library/unittest.html[unittest] framework
in the innermost-scope (line/function/class) possible. * https://pypi.python.org/pypi/flake8/1.3.1[flake8]
* https://github.com/GreenSteam/pep257/[pep257]
* http://pylint.org/[pylint]
* Custom checkers for untracked git files, whitespace/CRLF problems,
* `set_trace` invocations and VCS conflict markers.
- If you really think a check shouldn't be done, let me know! I'm still If you changed `setup.py`/`MANIFEST.in` and add the `--setup` argument, the
tweaking the parameters. following additional checkers are run:
run_profile needs pyprof2calltree and KCacheGrind and runs qutebrowser under a * https://pypi.python.org/pypi/pyroma/0.9.3[pyroma]
profiler to show you what uses the most time. This might come in handy when * https://github.com/mgedmin/check-manifest[check-manifest]
something is slow and you don't know what.
== Useful utilities == Please make sure this script runs without any warnings on your new
contributions. There's of course the possibility of false-positives, and the
following techniques are useful to handle these:
In the qutebrowser.utils.debug and -signal modules there are some useful * Use `_foo` for unused parameters, with `foo` being a descriptive name. Using
functions for debugging. In particular you should use set_trace from `_` is discouraged.
qutebrowser.utils.debug instead of pdb to set breakpoints or you'll get * If you think you have a good reason to suppress a message, add the following
annoying Qt error messages. comment:
+
----
# pylint: disable=message-name
----
+
Note you can add this per line, per function/class, or per file. Please use the
smallest scope which makes sense. Most of the time, this will be line scope.
+
* If you really think a check shouldn't be done globally as it yields a lot of
false-positives, let me know! I'm still tweaking the parameters.
== Style conventions == Profiling
---------
In the _scripts/_ subfolder there's a `run_profile.py` which profiles the code
and shows a graphical representation of what takes how much time.
It needs https://pypi.python.org/pypi/pyprof2calltree/[pyprof2calltree] and
http://kcachegrind.sourceforge.net/html/Home.html[KCacheGrind]. It uses the
built-in Python https://docs.python.org/3.4/library/profile.html[cProfile]
module.
Useful utilities
----------------
In the `qutebrowser.utils.debug` and `qutebrowser.utils.signal` modules there
are some useful functions for debugging. In particular you should use
`set_trace` from `qutebrowser.utils.debug` instead of `pdb` to set breakpoints
or you'll get annoying Qt error messages.
When starting qutebrowser with the `--debug` flag you also get useful debug
logs. You can add `--logfilter category[,category,...]` to restrict logging to
the given categories.
With `--debug` there are also some additional `debug-*` commands available, for
example `debug-all-objects` and `debug-all-widgets` which prints a list of all
Qt objects or widgets to the debug log -- this is very useful for finding
memory leaks.
Style conventions
-----------------
As you might have noticed, I *really* like clean and consistent code. While I As you might have noticed, I *really* like clean and consistent code. While I
won't reject your contribution when you don't follow the guidelines, I'd be won't reject your contribution when you don't follow the guidelines, I'd be
really glad if you'd do so. really glad if you'd do so.
qutebrowser's coding conventions are based on [PEP8][1] and the [Google Python qutebrowser's coding conventions are based on
style guidelines][2] with some additions: http://legacy.python.org/dev/peps/pep-0008/[PEP8] and the https://google-styleguide.googlecode.com/svn/trunk/pyguide.html[Google Python style guidelines] with some additions:
- Methods overriding Qt methods (obviously!) don't follow the naming schemes. * Methods overriding Qt methods (obviously!) don't follow the naming schemes.
* Everything else does though, even slots.
* Docstring are like described in
http://legacy.python.org/dev/peps/pep-0257/[PEP257] and the google guidelines.
* Class docstrings have additional `Attributes:`, `Class attributes:` and
`Signals:` sections, method/function docstrings have an `Emit:` section.
+
Example for a class docstring:
+
[source,python]
----
"""Some object.
- Everything else does though, even slots. Attributes:
blub: The current thing to handle.
- Docstring are like described in [PEP257][3] and the google guidelines. Signals:
Class docstrings have additional "Attributes", "Class attributes" and valueChanged: When a value changed.
"Signals" sections, method/function docstrings have an "Emit" section. arg: The new value
"""
----
+
Example for a method/function docstring:
+
[source,python]
----
"""Do something special.
Example for a class docstring: Args:
foo: ...
"""Some object. Return:
True if something, False if something else.
Attributes: Raise:
blub: The current thing to handle. ValueError if foo is None
Signals:
valueChanged: When a value changed.
arg: The new value
"""
Example for a method/function docstring:
"""Do something special.
Args:
foo: ...
Return:
True if something, False if something else.
Raise:
ValueError if foo is None
Emit:
value_changed
"""
- The layout of a module should be like this:
Emit:
value_changed
"""
----
+
* The layout of a module should be roughly like this:
- Copyright - Copyright
- GPL boilerplate - GPL boilerplate
- Module docstring - Module docstring
@ -82,18 +131,11 @@ style guidelines][2] with some additions:
- qutebrowser imports - qutebrowser imports
- functions - functions
- classes - classes
* The layout of a class should be like this:
- The layout of a class should be like this:
- docstring - docstring
- __magic__ methods - `__magic__` methods
- properties - properties
- _private methods - _private methods
- public methods - public methods
- on_* methods - `on_*` methods
- overrides of Qt methods - overrides of Qt methods
[1] http://legacy.python.org/dev/peps/pep-0008/
[2] https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
[3] http://legacy.python.org/dev/peps/pep-0257/