Please enable JavaScript.

Coggle requires JavaScript to display documents.

The Art of Readable Code - Coggle Diagram

- - - - :!!: Choosing specific words
      - :!!: Avoid generic names.
        Use names that describe the variable's value
      - :!!: Using concrete names instead of abstract
      - :!!: Attaching extra info to a name by using
        suffix or prefix
      - :!: Using name formatting to pack extra info
        Having different formats for different entities,
        the reader can easily identify what happening with a particular line
      - :question: Decide how long a name should be
        
        Throw unneeded words
        
        Don't use Acronyms or Abbreviations
        
        :check: Long names are not problem anymore since all the text editors support "word completion" on their search engine
    - - Prefer min, max for limits
      - Prefer first, last for inclusive ranges
      - Prefer begin, end for iclusive/exclusive ranges
      - For boolean, be sure it's clear what
        true and false really mean
    - - Organize declaration into blocks
      - Use methods to cleanup irregularity
      - :question: Use column alignment when helpful
      - Pick meaningful order
      - Break code into paragraphs
  - - - Facts that can quickly derived from the code itself
      - "Crutch comments" that make up for bad code - fix the code instead
    - - The "story" for how a constant got its value
      - Flaws in your code by using markers like TODO
      - Insights about why code is one way and not another - director commentary
      - Put yourself in the reader's shoes
        
        Anticipate which parts of your code will make readers say "Huh?" and comment those
        
        Document any surprising behavior an average reader wouldn't expect
        
        Use big picture comments at the file/class level to explain how all the piece fit together
        
        Summarize blocks of code with comments so that the reader doesn't get lost in the details
    - - Avoid pronouns like "it" and "this" when they can refer to multiple things
      - Describe function's behavior with as much precision as is practical
      - Illustrate your comment with carefully chosen input/output examples
      - State the high level intent of your code instead of the obvious details
      - Use inline comments to explain mysterious function arguments
      - Keep your comments brief by using words that packing a lot of meaning
- - - - :warning: Sometimes the order may avoid some accidental errors such as NPE
    - - :-1::skin-tone-3: One of the motivation for a single exit point is that the cleanup code at the bottom is guaranteed to be called
    - - Prefer dealing with the positive case first instead of negative
      - Prefer dealing with the simper case first
      - Prefer dealing with the more interesting or conspicuous case first
      - :check: In case of conflicts you have to make a judgment call
    - - remove nesting by returning early
      - remove nesting inside loops
        
        inside loops the return early analogous technique is the continue
  - - - It doesn't add clarification
      - It's used only once
      - Don't break down a complex expression
    - - Break a large class into smaller classes
      - Just move each definition right before its first use
      - Make as many methods static as possible
      - Prefer write-once variables - variables that are set only once (const, final, or other immutable) make code easier to understand
      - :warning: It's hard to keep track of where and how all those global variables are used
      - :check:: It effectively reduce the number of variables the reader has to think about at the same time