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

132
HACKING
View File

@ -1,50 +1,96 @@
== 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
https://docs.python.org/3.4/library/unittest.html[unittest] framework
* 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 changed `setup.py`/`MANIFEST.in` and add the `--setup` argument, the
following additional checkers are run:
* https://pypi.python.org/pypi/pyroma/0.9.3[pyroma]
* https://github.com/mgedmin/check-manifest[check-manifest]
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:
* Use `_foo` for unused parameters, with `foo` being a descriptive name. Using
`_` is discouraged.
* If you think you have a good reason to suppress a message, add the following
comment:
+
----
# pylint: disable=message-name # pylint: disable=message-name
in the innermost-scope (line/function/class) possible. ----
+
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.
- If you really think a check shouldn't be done, let me know! I'm still Profiling
tweaking the parameters. ---------
run_profile needs pyprof2calltree and KCacheGrind and runs qutebrowser under a In the _scripts/_ subfolder there's a `run_profile.py` which profiles the code
profiler to show you what uses the most time. This might come in handy when and shows a graphical representation of what takes how much time.
something is slow and you don't know what.
== Useful utilities == 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.
In the qutebrowser.utils.debug and -signal modules there are some useful Useful utilities
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.
== Style conventions == 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.
- Everything else does though, even slots.
- Docstring are like described in [PEP257][3] and the google guidelines.
Class docstrings have additional "Attributes", "Class attributes" and
"Signals" sections, method/function docstrings have an "Emit" section.
* 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: Example for a class docstring:
+
[source,python]
----
"""Some object. """Some object.
Attributes: Attributes:
@ -54,9 +100,12 @@ style guidelines][2] with some additions:
valueChanged: When a value changed. valueChanged: When a value changed.
arg: The new value arg: The new value
""" """
----
+
Example for a method/function docstring: Example for a method/function docstring:
+
[source,python]
----
"""Do something special. """Do something special.
Args: Args:
@ -71,9 +120,9 @@ style guidelines][2] with some additions:
Emit: Emit:
value_changed value_changed
""" """
----
- The layout of a module should be like this: +
* 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/