Meaningful Names “Variables should be named with the same level of care given to naming a newborn child” Use pronounceable names genymdhms Use searchable names Length of a name should correspond to the size of its scope Avoid disinformation Inconsistent spellings
Meaningful Names Make meaningful distinctions Writing code solely to appease the compiler Noise words Product/ProductInfo/ProductData Use intention-revealing names Why does it exist? What does it do? How is it used? One word per concept...but don’t pun Don’t add gratuitous context
Functions Small Smaller ○ Smaller than that if/else/while: 1 line blocks Do One Thing Problem: What is “one thing”? ○ “If a function does only those steps that are one level below the stated name of the function, then the function is doing one thing” ○ “A function is doing more than one thing if you can extract another function from it with a name that is not merely a restatement of its implementation” Sections within functions – obviously doing more than one thing
Functions The stepdown rule Top-down narrative switch statements – always do N things Should appear only once to create polymorphic objects, hidden from rest of system Function arguments Ideal # of arguments: 0 includeSetupPage() easier to understand than includeSetupPageInto(newPagecontent) If the input’s going to be transformed, it should be returned
Functions Flag arguments Immediately imply that the function does more than one thing! Command query separation Either change the state of an object, or return some information about that object Extract try/catch blocks Allows you to understand, then ignore, error processing Error handling is one thing!
Comments “Comments are always failures” Compensate for failure to express in code They lie – we can’t realistically maintain them Explain yourself in code // Check to see if the employee is eligible for full benefits if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) vs. if (employee.isEligibleForFullBenefits())
Comments Good comments Informative Explain of intent Clarification – when it’s code you can’t alter Warning of consequences Bad comments Redundant Misleading Mandated Journal comments Noise comments (“Default constructor”) Closing brace comments Commented-out code HTML comments Nonlocal information TMI Javadocs in nonpublic code
Formatting Small files usually easier to understand than large files Newspaper metaphor Detail should increase as we move downward Vertical openness between concepts Vertical density & closeness implies close association Horizontal openness Accentuate operator precedence?
Objects and Data Structures Objects: hide data behind abstractions and expose functions that operate on that data OO code: easy to add new classes; hard to add new functions Data structures: expose their data and have no meaningful functions Procedural code: easy to add new functions; hard to add new data structures
Objects and Data Structures Law of Demeter: module shouldn’t know about the innards of the objects it manipulates Don’t expose internal structure through accessors “Train wrecks” final String outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath(); Hybrids Functions that do significant things, but also public variables/accessors Hard to add both new functions and new data structures Leads to feature envy
Error handling If it obscures logic, it’s wrong Exceptions rather than return codes Use unchecked exceptions Checked: low level changes propagate up Breaks encapsulation Wrap 3rd-party APIs Don’t return null – throw exception or return a special-case object Don’t pass null
Classes ...should also be small In terms of responsibilities SRP – should have ONE reason to change Big # of small classes vs. Small # of large classes Cohesion OCP – open for extension, closed for modification