diff --git a/src/banman.h b/src/banman.h
--- a/src/banman.h
+++ b/src/banman.h
@@ -24,20 +24,35 @@
 class CNetAddr;
 class CSubNet;
 
-// Denial-of-service detection/prevention
-// The idea is to detect peers that are behaving
-// badly and disconnect/ban them, but do it in a
-// one-coding-mistake-won't-shatter-the-entire-network
-// way.
-// IMPORTANT:  There should be nothing I can give a
-// node that it will forward on that will make that
-// node's peers drop it. If there is, an attacker
-// can isolate a node and/or try to split the network.
-// Dropping a node for sending stuff that is invalid
-// now but might be valid in a later version is also
-// dangerous, because it can cause a network split
-// between nodes running old code and nodes running
-// new code.
+// Banman manages two related but distinct concepts:
+//
+// 1. Banning. This is configured manually by the user, through the setban RPC.
+// If an address or subnet is banned, we never accept incoming connections from
+// it and never create outgoing connections to it. We won't gossip its address
+// to other peers in addr messages. Banned addresses and subnets are stored to
+// banlist.dat on shutdown and reloaded on startup. Banning can be used to
+// prevent connections with spy nodes or other griefers.
+//
+// 2. Discouragement. If a peer misbehaves enough (see Misbehaving() in
+// net_processing.cpp), we'll mark that address as discouraged. We still allow
+// incoming connections from them, but they're preferred for eviction when
+// we receive new incoming connections. We never make outgoing connections to
+// them, and do not gossip their address to other peers. This is implemented as
+// a bloom filter. We can (probabilistically) test for membership, but can't
+// list all discouraged addresses or unmark them as discouraged. Discouragement
+// can prevent our limited connection slots being used up by incompatible
+// or broken peers.
+//
+// Neither banning nor discouragement are protections against denial-of-service
+// attacks, since if an attacker has a way to waste our resources and we
+// disconnect from them and ban that address, it's trivial for them to
+// reconnect from another IP address.
+//
+// Attempting to automatically disconnect or ban any class of peer carries the
+// risk of splitting the network. For example, if we banned/disconnected for a
+// transaction that fails a policy check and a future version changes the
+// policy check so the transaction is accepted, then that transaction could
+// cause the network to split between old nodes and new nodes.
 
 class BanMan {
 public:
@@ -71,17 +86,6 @@
     CClientUIInterface *m_client_interface = nullptr;
     CBanDB m_ban_db;
     const int64_t m_default_ban_time;
-
-    /**
-     *  Individual addresses that of peers that misbehave (see Misbehaving() in
-     *  net_processing) are not banned but discouraged: we still allow incoming
-     *  connections from them, but prefer them for eviction. Similar to banned
-     *  IPs, we never make outgoing connections to them, and do not rumour them
-     *  to other peers.
-     *
-     *  This is implemented as a bloom filter. We can (probabilistically) test
-     *  for membership, but can't list or unban automatically banned peers.
-     */
     CRollingBloomFilter m_discouraged GUARDED_BY(m_cs_banned){50000, 0.000001};
 };