add TODO.rst

Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>

TODO.rst

@@ -0,0 +1,127 @@
+.. 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.