I feel that our current document in software development is not yet systematic enough to allow client code to avoid code violation only by reading document of callees, whether in object-oriented or process-oriented, It is hard to describe the impact of a method on object that is visible to the outside in the document, and the introduction of inheritance and polymorphism exacerbates this problem.

Programmers often use high-level understanding sentences to describe what the method does and how it affects the outside object, but such document is rarely useful for discovering code-level violation.

The ideal state I think is: “We can get the necessary information to deduce whether code violation will occur just only by reading document of callees.”, rather than searching necessary information in the source code after we fail to do the same in the document, or expecting to find all the problems that can not be deduced from the document by testing. But this ideal state seems to haven’t been achieved right now.

There is an abstract example code to explain a situation that client code cannot prevent code violation from occurring only by reading document of callees. The example code is an observer pattern situation and I cut out the code that wouldn’t prevent the problem from occurring.

class ClassA {
    /**
     * only be called once
     */ 
    public void foo() { /*...*/ }
}

// observer interface
Interface IClassB {
    /**
     * observer recive broadcast of subject.
     */ 
    public void foo(ClassA a);
}

class ClassB implements IClassB{
    /**
     * observer recive broadcast of subject. execute a.foo.
     */
    @Override 
    public void foo(ClassA a) {
        // ...
        a.foo();
        // ...      
    }
}

// subject
class ClassC {
    /**
     * broadcast to all observers, exectue ib.foo(a) for every observer;
     */
    public void foo(ClassA a) {
        // ...
        ib.foo(a);
        // ...
    }
}

// client code follow:
/*there is a ClassA instance whose foo method hasn't been called.*/
a.foo();
/*
According to the ClassC::foo document, we cannot know which subclass's IClassB::foo actcually be called, therefore, it is impossible to deduce what c.foo(a) will do from subclass document, then the client code is unable to know whether code violation will occur while executing c.foo(a). it is noted that client code is unable to know what kind of observers which c will broadcast to in many observer pattern applications.
*/
c.foo(a);

[repeat last comment:cIn the last line, according to the ClassC::foo document, we cannot know which subclass’s IClassB::foo actcually be called, therefore, it is impossible to deduce what c.foo(a) will do from subclass document, then the client code is unable to know whether code violation will occur while executing c.foo(a). it is noted that client code is unable to know what kind of observers c will broadcast to in many observer pattern applications.

The above is just one example of client code cannot prevent code violation from occurring only by reading document of callees, this problem must be also hidden in many situations. So, I want to know what happened, is there no perfect and reliable document specification? or is the ideal state I mentioned above was never pursued in programming field? How do I deal with this problem?