Some pieces of code are just beautiful. One of my favorite methods from the past year is part of CodeCity:
CCCuboid>>verticesFor: anObject | xSize ySize zSize p1 p2 p3 p4 p5 p6 p7 p8 | xSize := self widthFor: anObject. ySize := self heightFor: anObject. zSize := self depthFor: anObject. p1 := CCPoint x: 0 y: 0 z: zSize. p2 := CCPoint x: xSize y: 0 z: zSize. p3 := CCPoint x: 0 y: ySize z: zSize. p4 := CCPoint x: xSize y: ySize z: zSize. p5 := CCPoint x: 0 y: 0 z: 0. p6 := CCPoint x: xSize y: 0 z: 0. p7 := CCPoint x: 0 y: ySize z: 0. p8 := CCPoint x: xSize y: ySize z: 0. ^ OrderedCollection new add: p1; add: p2; add: p3; add: p4; add: p5; add: p6; add: p7; add: p8; yourself
No. It’s not a joke. Yes, I know that it has p1 ... p8 in there. And, I know it is difficult to figure out what it does exactly. Please indulge me for a little while and let’s take a closer look at it.
The method seems to build some points in a three dimensional space (due to the x:y:z:
selector) that are related to a cuboid object. The only more meaningful names we have there are =xSize=, =ySize=, =zSize= which relate to dimensions, and these variables are used for constructing the p1 ... p8 points. Given that we have 8 points, and that a cuboid shape is made of 8 points, it likely means that we deal with a factory method that constructs the cuboid. The only problem is: which point corresponds to which point?
One approach to address this question is to name the variables like frontTopLeft
and backBottomRight
. That’s what the book would tell you. But, there is another way. The reason I like this method, is due to the comment that I intentionally omitted above. Take a look again.
CCCuboid>>verticesFor: anObject “ 7 - - - 8 / | / | 3 - - - 4 | | 5- - |- 6 | / | / 1 - - - 2 “ | xSize ySize zSize p1 p2 p3 p4 p5 p6 p7 p8 | xSize := self widthFor: anObject. ySize := self heightFor: anObject. zSize := self depthFor: anObject. p1 := CCPoint x: 0 y: 0 z: zSize. p2 := CCPoint x: xSize y: 0 z: zSize. p3 := CCPoint x: 0 y: ySize z: zSize. p4 := CCPoint x: xSize y: ySize z: zSize. p5 := CCPoint x: 0 y: 0 z: 0. p6 := CCPoint x: xSize y: 0 z: 0. p7 := CCPoint x: 0 y: ySize z: 0. p8 := CCPoint x: xSize y: ySize z: 0. ^ OrderedCollection new add: p1; add: p2; add: p3; add: p4; add: p5; add: p6; add: p7; add: p8; yourself
All of a sudden, the cryptic numbers have a clear meaning, don’t they? This is beautiful.
Working code is for the machine. Understandable code is for humans. The main responsibility of a developer is for the humans that consume that code, not for the machine. Achieving this requires imagination and creativity.