docker-offlineimap/TODO.rst
Nicolas Sebrecht 61d292bb85 add TODO.rst
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>
2015-03-07 19:56:05 +01:00

128 lines
4.3 KiB
ReStructuredText

.. vim: spelllang=en ts=2 expandtab :
.. _coding style: https://github.com/OfflineIMAP/offlineimap/blob/next/docs/CodingGuidelines.rst
============================
TODO list by relevance order
============================
Should be the starting point to improve the `coding style`_.
Write your WIP directly in this file.
TODO list
---------
* Better names for variables, objects, etc.
* Improve comments.
Most of the current comments assume a very good
knowledge of the internals. That sucks because I guess nobody is
anymore aware of ALL of them. Time when this was a one guy made
project has long passed.
* Better policy on objects.
- Turn ALL attributes private and use accessors. This is not
"pythonic" but such pythonic thing turn the code into intricated
code.
- Turn ALL methods not intended to be used outside, private.
* Revamp the factorization.
It's not unusual to find "factorized" code
for bad reasons: because it made the code /look/ nicer, but the
factorized function/methods is actually called from ONE place. While it
might locally help, such practice globally defeat the purpose because
we lose the view of what is true factorized code and what is not.
* Namespace the factorized code.
If a method require a local function, DON'T USE yet another method. Use a
local namespaced function.::
class BLah(object):
def _internal_method(self, arg):
def local_factorized(local_arg):
# local_factorized's code
# _internal_method's code.
Python allows local namespaced functions for good reasons.
* Better inheritance policy.
Take the sample of the folder/LocalStatus(SQlite) and folder/Base stuffs. It's
*nearly IMPOSSIBLE* to know and understand what parent method is used by what
child, for what purpose, etc. So, instead of (re)defining methods in the wild,
keep the well common NON-redefined stuff into the parent and define the
required methods in the childs. We really don't want anything like::
def method(self):
raise NotImplemented
While this is common practice in Python, think about that again: how a
parent object should know all the expected methods/accessors of all the
possible kind of childs?
Inheritance is about factorizing, certainly **NOT** about **defining the
interface** of the childs.
* Introduce as many as intermediate inherited objects as required.
Keeping linear inheritance is good because Python sucks at playing
with multiple parents and it keeps things simple. But a parent should
have ALL its methods used in ALL the childs. If not, it's a good
sign that a new intermediate object should be introduced in the
inheritance line.
* Don't blindly inherit from library objects.
We do want **well defined interfaces**. For example, we do too much things
like imapobj.methodcall() while the imapobj is far inherited from imaplib2.
We have NO clue about what we currently use from the library.
Having a dump wrappper for each call should be made mandatory for
objects inherited from a library. Using composed objects should be
seriously considered in this case, instead of using inheritance.
* Use factories.
Current objects do too much initialization stuff varying with the context it
is used. Move things like that into factories and keep the objects definitions
clean.
* Make it clear when we expect a composite object and what we expect
exactly.
Even the more obvious composed objects are badly defined. For example,
the ``conf`` instances are spread across a lot of objects. Did you know
that such composed objects are sometimes restricted to the section the
object works on, and most of the time it's not restricted at all?
How many time it requires to find and understand on what we are
currently working?
* Seriously improve our debugging/hacking sessions (AGAIN).
Until now, we have limited the improvements to allow better/full stack traces.
While this was actually required, we now hit some limitations of the whole
exception-based paradigm. For example, it's very HARD to follow an instance
during its life time. I have a good overview of what we could do in this area,
so don't matter much about that if you don't get the point or what could be
done.
* Support Python 3.
* Support Unicode.