Why are private methods good for documentation? They shouldn't even be documented save for inline comments. The whole idea of privacy in my mind is that the onl

Why are private methods good for documentation? They shouldn't even be documented save for inline comments. The whole idea of privacy in my mind is that the only person or people who should know that these functions even exist are those who maintain the class/library/framework. This helps immensely because when you want to refactor you know EXACTLY which method signatures or attributes have to be supported for backward compatibility. You can really keep on top of things, and as long as you took the time to create a flexible API, you can handle change gracefully. I don't even unit test my private methods because I don't even care about them or what they do. I only care that some data is passed to a public API and returns the correct result. They are there, as you say, purely as a means to organise my code. For example, in my last company I wrote this ORM in Moose. I released it. And the guys I was working with just didn't get the concept of Moose. They kept accessing the attributes from the underlying blessed hash like they did before rather than the accessors. It still worked because internally Moose stores stuff the way Conway recommended in OOP Perl (which was a weird decision imho). One day I renamed one of my database columns and so had to rename my accessor and created a manual function that warned of "obselete call to accessor x" whilst returning the new column name... backwards compatibility, yay! But they didn't see this because they didn't use the accessor and now all their manual hash accessing was returning undefined or null or whatever it is. Of course it only took me going over to their table and explaining to them how Moose worked or getting together for a meeting. Fine. But that was a company with a technical team of around 10 people. Now I work for a big tech company, and I'm in charge of a framework again except now its JavaScript which has the same problems when people force this classical inheritance pattern and now when some guy doesn't get it he's in another building or another country and did so in a repository I didn't even know existed and his code that breaks my encapsulation is in a production device and when I refactor my code I have the possibility that I break live code on some project or some device I don't know about. So yeah, privacy is an important concept and if you don't think so I would say it is you who lives in a superficial bubble where everyone who uses your API or works on your code can be trusted to have good sense.