Episode 05 – Form

Clean Code

Episode 05

The fifth episode talks about layout on white space, indentation, comments, classes vs data structure, boundary crossing, .

  • Comments
    • Coding Standards
    • Comments should be rare
      • If comments are too frequent, then it becomes ignored.
      • Therefore, comments should be rare.
    • Comments are failure
      • The goal for a programmer is to write code so clear and so well that comments are unnecessary.
    • Comments are lie
      • Over time, comments degrade to disinformation and become lie because comments usually are non-local.
    • Good comments
      • Legal comments
      • Informative comments
      • Public API documentation
    • Bad comments
      • Mumbling in the comments
      • Redundant explanation
      • Mandated Redundancy
      • Delete wrong or disinformation comments
      • Journal comments
      • Noise comment (default constructor)
      • Big banner comments
      • closing brace comments
      • Attribution comments (added by…)
      • HTML in comments
      • Non-Local Information – no way for far away modification to know this comment and change it when necessary
      • comment out code
    • Explanatory structure
      • Make code read well instead of using comments
  • Formatting
    • White space
      • white space carry information and should be use with care
      • getting the code to communicate is more important than getting it to work
    • File Size
      • test driven development project tend to give smaller file size
      • large file tend to be the dumping ground of things we did not take the time to organize.
    • Vertical Formatting
      • Use white space to separate things that needed to be separated. Decide consistency number of white space for the same type of separation.
      • Things are similar should be vertically close.
    • Horizontal Formatting
      • You never have to scroll to see the whole line
    • Indentation
      • Use spaces (2 characters)
      • use the same style for the whole team
  • Classes
    • from outside, the classes does not have any variable but only methods
    • Tell don’t ask. Try not to expose the private variable to outside by using getter and setter
    • More cohesive method will manipulate more private variable. Getter and setter are not cohesive.
    • Methods hide the data and expose only the abstract form of the data
  • Data Structure
    • Data structure has public variables and no methods or method that expose implementation.
    • Data structure relates to switch statement is similar to classes related to polymorphism.
    • Object protect you from new type. When you add method to base class, all plug in and derive class must re-compile and breaks independence deployablility
    • Data structure is immune to additional function because it just need a new switch case.
    • The expression problem – protect from both new type and new method
  • Boundaries
    • Boundary examples are view from model, main from application, database from domain (concrete from domain).
    • For each boundary, one side is concrete and the other side is abstract. Have the source code dependency point away from concrete toward abstract.
    • E.g. separate database from application and domain objects by using a DB interface layer where the SQL code reside. Do not put the SQL code in the application and domain objects. The interface layer should depend on application and domain objects.
    • The impedance mismatch
      • Impedance mismatch is between relational database and object oriented programming. Can not force a data structure to be an object.
      • DB interface layer convert between the data from database to become a business object
      • The abstract class is reside in application and the layer uses inheritance on those abstract class so the source code dependency is pointing away from the concrete.
  • References
    • The elements of programming style by Kerninghan and Plauger
Advertisements