ZooKeeper: added comment [#CLICKHOUSE-2]

dbms/src/Common/ZooKeeper/ZooKeeperImpl.h

@@ -24,6 +24,52 @@
 #include <functional>
 
 
+/** ZooKeeper C++ library, a replacement for libzookeeper.
+  *
+  * Motivation.
+  *
+  * libzookeeper has many bugs:
+  * - segfaults: for example, if zookeeper connection was interrupted while reading result of multi response;
+  * - memory corruption: for example, as a result of double free inside libzookeeper;
+  * - no timeouts for synchronous operations: they may stuck forever under simple Jepsen-like tests;
+  * - logical errors: for example, chroot prefix is not removed from the results of multi responses.
+  * - data races;
+  *
+  * The code of libzookeeper is over complicated:
+  * - memory ownership is unclear and bugs are very difficult to track and fix.
+  * - extremely creepy code for implementation of "chroot" feature.
+  *
+  * As of 2018, there are no active maintainers of libzookeeper:
+  * - bugs in JIRA are fixed only occasionaly with ad-hoc patches by library users.
+  *
+  * libzookeeper is a classical example of bad code written in C.
+  *
+  * In Go, Python and Rust programming languages,
+  *  there are separate libraries for ZooKeeper, not based on libzookeeper.
+  * Motivation is almost the same. Example:
+  * https://github.com/python-zk/kazoo/blob/master/docs/implementation.rst
+  *
+  * About "session restore" feature.
+  *
+  * libzookeeper has the feature of session restore. Client receives session id and session token from the server,
+  *  and when connection is lost, it can quickly reconnect to any server with the same session id and token,
+  *  to continue with existing session.
+  * libzookeeper performs this reconnection automatically.
+  *
+  * This feature is proven to be harmful.
+  * For example, it makes very difficult to correctly remove ephemeral nodes.
+  * This may lead to weird bugs in application code.
+  * For example, our developers have found that type of bugs in Curator Java library.
+  *
+  * On the other side, session restore feature has no advantages,
+  *  because every application should be able to establish new session and reinitialize internal state,
+  *  when the session is lost and cannot be restored.
+  *
+  * This library never restores the session. In case of any error, the session is considered as expired
+  *  and you should create a new instance of ZooKeeperImpl object and reinitialize the application state.
+  */
+
+
 namespace CurrentMetrics
 {
     extern const Metric ZooKeeperSession;