offlineIMAP3/TODO.rst

.. 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 Unicode.