Pr ogr amme r 's Doze n T hir te e n R e c omme ndations for R e vie wing, R R e fac tor e fac tor ing and R ing and R e gaining Contr e gaining Contr ol of Code ol of Code Ke vlin He nne y ke vlin@c ur ke vlin@c ur br br alan.c om alan.c om
programmer a person who writes computer programs. d dozen a group or set of twelve. f l The New Oxford Dictionary of English Asymmetric bounds are most convenient to program in a language like C in Asymmetric bounds are most convenient to program in a language like C in which arrays start from zero: the exclusive upper bound of such an array is equal to the number of elements! Thus when we define a C array with [12] elements, 0 is inclusive lower bound and [12] the exclusive upper bound for the elements, 0 is inclusive lower bound and [12] the exclusive upper bound for the subscripts of the array. Andrew Koenig A baker's dozen contains thirteen items as opposed to the familiar twelve. This dates from the time when bakers were subject to heavy fines if they served under-weight bread. To avoid this danger bakers provided a surplus number of l loaves, the thirteenth loaf in the dozen being called the vantage loaf. h h h l f h d b ll d h l f Lock, Stock & Barrel
Code Meaning 0 Prefer Code to Comments 1 1 Follow Consistent Form Follow Consistent Form 2 Employ the Contract Metaphor Code Dependencies p 3 Express Independent Ideas Independently p p p y 4 Encapsulate 5 Parameterize from Above 6 Restrict Mutability of State 7 Favour Symmetry over Asymmetry Code Execution 8 Sharpen Fuzzy Logic 9 Go with the Flow 10 10 Let Code Decide Let Code Decide Code Consolidation 11 Omit Needless Code 12 Unify Duplicate Code y p
e c omme ndation 0 Code to Comme nts e fe r Pr R
1. If a program is incorrect, it matters little what the documentation says. documentation says. 2. If documentation does not agree with the code, it is not worth much. 3 3. Consequently code must largely document itself If it Consequently, code must largely document itself. If it cannot, rewrite the code rather than increase the supplementary documentation. Good code needs fewer comments than bad code does comments than bad code does. 4. Comments should provide additional information that is not readily obtainable from the code itself. They should never parrot the code should never parrot the code. 5. Mnemonic variable names and labels, and a layout that emphasizes logical structure, help make a program self ‐ documenting documenting. Kernighan and Plauger
m m or or e c omme ndation 1 ollow Consiste nt F ollow Consiste nt F R F F
Th This principle, that of parallel l h f ll l construction, requires that expressions similar in context and i i il i d function be outwardly similar. The likeness of form enables the reader lik f f bl h d to recognize more readily the lik likeness of content and function. f d f i Strunk and White Strunk and White Strunk and White Strunk and White
Name based on Client implementation Implementation Implementation name Name based on Client client usage client usage Implementation name
ac t Me taphor e c omme ndation 2 p mploy the y p Contr E R
contract a written or spoken agreement, especially one concerning p g , p y g employment, sales, or tenancy, that is intended to be enforceable by law. metaphor a figure of speech in which a word or phrase is applied to an object or action to which it is not literally applicable. b h h l ll l bl a thing regarded as representative or symbolic of something else, � especially something abstract. p y g The New Oxford Dictionary of English
postcondition: postcondition: given: returns size() == 0 expectedSize = size() + (contains(newItem) ? 0 : 1) postcondition: postcondition: postcondition: returns >= 0 get(0).equals(newItem) && size() == expectedSize public class RecentlyUsedList { precondition: public boolean isEmpty() ... p p y() index >= 0 && index < size() index >= 0 && index < size() public int size() ... postcondition: public void add(String newItem) ... returns != null public String get(int index) ... public boolean contains(String item) public boolean contains(String item) ... public void clear() ... ... } } postcondition: postcondition: returns whether get(index).equals(item) for postcondition: any index in [ 0..size() ) any index in [ 0..size() ) isEmpty() ()
@Test public void constructor() Constructor Constructor Constructor Constructor { RecentlyUsedList list = new RecentlyUsedList(); () assertEquals(0, list.size()); } @Test public void add() { Add Add Add Add RecentlyUsedList list = new RecentlyUsedList(); RecentlyUsedList list new RecentlyUsedList() list.add("Aardvark"); assertEquals(1, list.size()); list.add("Zebra"); list.add("Mongoose"); assertEquals(3, list.size()); list add("Aardvark"); list.add( Aardvark ); assertEquals(3, list.size()); } @Test public void get() { G Get et RecentlyUsedList list = new RecentlyUsedList(); y y (); list.add("Aardvark"); list.add("Zebra"); list.add("Mongoose"); assertEquals("Mongoose", list.get(0)); assertEquals("Zebra", list.get(1)); assertEquals("Aardvark", list.get(2)); list.add("Aardvark"); ( ) assertEquals("Aardvark", list.get(0)); assertEquals("Mongoose", list.get(1)); assertEquals("Zebra", list.get(2)); bool thrown; try { list.get(3); thrown = false; } catch(IndexOutOfBoundsException) { thrown = true; thrown = true; } assertTrue(thrown); }
@Test public void initialListIsEmpty() { Initial list Initial list Initial list is Initial list is is empty is empty empty empty RecentlyUsedList list = new RecentlyUsedList(); RecentlyUsedList list = new RecentlyUsedList(); assertEquals(0, list.size()); } @Test public void additionOfSingleItemToEmptyListIsRetained() { Addition o ddition of sin f f single item to g g le item to RecentlyUsedList list = new RecentlyUsedList(); y y (); list.add("Aardvark"); empty list is empty list is retained retained assertEquals(1, list.size()); assertEquals("Aardvark", list.get(0)); } @Test public void additionOfDistinctItemsIsRetainedInStackOrder() Addition of Addition of distinct items is Addition of Addition of distinct items is distinct items is distinct items is { { RecentlyUsedList list = new RecentlyUsedList(); retained in stack order retained in stack order list.add("Aardvark"); list.add("Zebra"); list.add("Mongoose"); assertEquals(3, list.size()); assertEquals("Mongoose" list get(0)); assertEquals( Mongoose , list.get(0)); assertEquals("Zebra", list.get(1)); assertEquals("Aardvark", list.get(2)); } @Test Dupli Duplicate e it item ems are moved to s are moved to public void duplicateItemsAreMovedToFrontButNotAdded() { RecentlyUsedList list = new RecentlyUsedList(); RecentlyUsedList list = new RecentlyUsedList(); front f f ront but not a b b ut not add dd d dded list.add("Aardvark"); list.add("Mongoose"); list.add("Aardvark"); assertEquals(2, list.size()); assertEquals("Aardvark", list.get(0)); assertEquals("Mongoose", list.get(1)); q g g } @Test(expected=IndexOutOfBoundsException.class) Out of Out of range index throws range index throws public void outOfRangeIndexThrowsException() { RecentlyUsedList list = new RecentlyUsedList(); except exception list.add("Aardvark"); list.add("Mongoose"); ( g ); list.add("Aardvark"); list.get(3); }
e ss Inde pe nde nt Ide as Inde pe nde ntly y e c omme ndation 3 p p xpr R p E
Pure Interface Layer Pure Interface Layer «interface» Interfaces may extend Interfaces may extend UsageInterface interfaces, but there is no interfaces, but there is no implementation defined in implementation defined in this layer. this layer. this layer this layer Common Code Layer Common Code Layer Onl Onl Only abstract classes are Only abstract classes are abstract classes are abstract classes are defined in this layer, possibly defined in this layer, possibly CommonCode CommonCode with inheritance, factoring out with inheritance, factoring out any common implementation. any common implementation. Concrete Class Layer Concrete Class Layer Only concrete classes are Only concrete classes are defined, and they do not defined, and they do not ConcreteLeaf ConcreteLeaf ConcreteLeaf inherit from one another. inherit from one another.
e c omme ndation 4 nc apsulate nc apsulate E E R
encapsulate enclose (something) in or as if in a capsule. express the essential feature of (someone or something) succinctly express the essential feature of (someone or something) succinctly. � � � enclose (a message or signal) in a set of codes which allow use by or transfer through different computer systems or networks. provide an interface for (a piece of software or hardware) to allow or provide an interface for (a piece of software or hardware) to allow or � � simplify access for the user. The New Oxford Dictionary of English
Recommend
More recommend
