Advertisement

Defensive Copying and the Contract

Bill Venners: If I defensively copy an object passed into, say, a constructor, should I document that defensive copying as part of the class's contract? If I don't document it, I may have the flexibility later to remove the defensive copy for a performance tweak. But if I don't document it, client programmers can't be sure the constructor will do a defensive copy. So they may do a defensive copy themselves before they pass the object to my constructor. Then we'll have two defensive copies.

Josh Bloch: If you haven't documented it, is a client permitted to modify the parameter or isn't he? Obviously, if you have a paranoid client, he won't modify the parameter because it might hurt your module. In practice, programmers aren't that paranoid -- they do modify. All things being equal, if the documentation doesn't say you must not do this, the programmer will do it. So, you are signing on for that defensive copy whether or not you document it. And you might as well document it because then even the paranoid client will know that, yes, he has the right to do anything he wants with the input parameter.

Ideally, you should document that you are doing a defensive copy. However, if you look back at my code, you'll find that I haven't. I defend against sloppy clients, but I haven't always made this explicit in the documentation.

One problem with writing widely distributed source code is that people can go back and look at your code and say: Ah, but you didn't do it here. Generally speaking, I respond: Well, I learned a few things since I wrote that; now I know I have to do it. In this case, it's a question of how careful is your documentation? I'm probably not careful enough, and, yes, I think it's worth being careful.