A Philosophy of Software Design

by John Ousterhout

The interface comment for a method includes both higher-level information for abstraction and lower-level details for precision: