Chapter 5: Candy-Machine Interfaces

  • make it hard to ignore important details by making them explicit in the design;
  • create interface that are easy to use and understand;
  • return values must not carry error codes;
  • look for and eliminate flaws in your interfaces so others don’t follow your mistakes;
  • use single responsibility principle for methods, don’t write multi-purpose methods;
  • define explicit method arguments. Consider how others will call your method. Think about the method’s purpose and if it makes sense to call the method with an odd value. If it makes sense, the odd value should be treated differently in the method, otherwise don’t stress about it, just assert it;
  • write methods which cannot fail if they are given valid inputs;
  • examine your interfaces from the caller’s point of view;
  • make the code intelligible at the point of call by using proper arguments. Avoid using boolean and magic number arguments, this is usually a smell of the method having two purposes instead of one and usually ends up in splitting the method in two others;
  • comment code to emphasize a potential hazard if the hazard cannot be removed. Comment odd cases and what to be careful around, but again, only if the hazard cannot be removed. Comments should not be an excuse to write poor quality code;
  • the devil is in the details. Write everything as clear and obvious as possible.