Dano Manion

Programming General Notes

  • Learning a programming language requires getting acquainted with its syntax, the set of forms and structures that make up legal programs, and semantics, the meaning or behavior of those forms.
  • It’s okay to write pseudocode, writing out how a program would run in plain english. I’ve done this in describing functionality.
  • Make your code naturally readable for others, after all we write code for each other, not just machines.
  • Another fact of life related to software development in general is that usually more time is spent reading code than writing it.
  • When possible try to minimize mutable state. This way the “Turning it off and turning it on again” process continues to work. Okay-okay, it’s mostly to help prevent bugs in your code that may be introduced by unforeseen changes in variables.

Terms

  • API: is a programmer contract.

What is software construction?

  • Software is a complicated process and making good software requires a number of important processes.
    • Problem Definition
    • Requirements Development
    • Construction Planning
    • Software Architecture (High Level Design)
    • Detailed Design
    • Coding and debugging
    • Unit Testing
    • Integration Testing
    • Integration
    • System Testing
    • Corrective Maintenance
  • “construction is not at all mechanical and involves substantial creativity and judgment.”
  • Construction is a large and central part of software Development (typically takes 30% to 80%)

Names

  • Names are not just convenience, they are a tool
  • Reveal Your Intent: if you need a comment for this, you have chosen poorly.
    • Examples:
      • calD(mm,dd,yy); should be CalendarDate(resultMonth, resultDay, resultYear)
  • Avoid Disinformation: Do your names actually mean what they represent?
    • Giving a concrete name to an abstract class
  • Write clear, pronounceable names. This makes it easier to communicate with each other.

    // Example of bad names
    int qty_tests = 0;
    int qty_pass_m = 0;
    int qty_pass_s = 0;
    int qty_skip = 0;
    int qty_fail = 0;
    
    // Examples of how these names could have been better
    int total_test = 0;
    int passed_test = 0;
    int passed_scenarios = 0
    int passed_methods = 0;
    int skipped_test = 0;
    int failed_test = 0;
    
  • Avoid Encodings
    • Avoid “Hungarian Notation” Encodings. We are no longer in the 1990’s (well, except for Portland, OR ;p)
    • Just use names, let your IDE inform you of type or other details of your variables
  • Parts of Speech
    • Variables and Classes are nouns
      • YES: Account, MessageParser
      • NO: Manager, Processor, Info
      • Boolean should be written like predicates
        • boolean isEmpty;
        • boolean isTerminated;
    • Methods are verbs
      • postPayment(payment);
      • getPrice();
  • Code should be readable

    if (employee.isLate())
      employee.reprimand();
    
  • Scope length should be proportional to Scope usage.
    • Variables: The larger the scope, the longer and more descriptive the name should be.

      • Names that are encapsulated to one statement can actually be short, however if the Variable name is used throughout the code, the name should be longer. This is because you can easily see the within context.
        • the longer the scope of the variable the longer the Variable
        • the shorter the scope, the shorter the name

          for (ITestResult tr: m_configIssues) { Element e = createElement(document, tr); rootElement.appendChild(e); }

          for (i = 0; i <= 9; i++) { largeScopeVariable[i] = “Proper use of scope.” }

      • Functions & Classes : the larger the scope, the smaller the name, this leads to easier to read code.

      • However with functions, this role is almost reversed. Overall we should do what is below.
        • public functions: have big long scopes, we actually want to give them short names
          • because they are called from multiple places,
        • private functions: contain a lot of detail, and should have long description in their names
          • because they almost act like comments and are available in a small area
        • derived classes
          • account, savings_account, the more specific the more adjectives are added

What is the difference between a Parameter and and Argument?

  • A parameter is a variable in a method definition. When a method is called, the arguments are the data you pass into the method’s parameters. Parameter is variable in the declaration of function. Argument is the actual value of this variable that gets passed to function.
  • Gives a good example

Functions

  • A function should do only ONE thing and do it well, and it should do it only.
  • small, and even smaller then you think
  • 4 lines, 10 lines max (this feels like an attempt to be sure you are doing functional programming)
  • Tiny functions are sooo much easier to follow then a nest of embed functions plus they can be utilized in different and interesting ways
  • Extract functions till you can’t extract no more. “Extract till you drop.” - Robert C. Martin (Uncle Bob)
    • {}’s show an opportunity for extraction
  • The large function is where classes go to hide.

Templating Languages vs Native Approach

Handlebars / Mustache Style Languages vs React like Languages

  • Templating: (are more Expressive)
    • Adds Learning Complexity: adds an entire language to your stack
      • Is another tool or asset that adds Complexity, which could lead to problems down the line
    • Comes at a Social Costs: One has to learn a new unique language
    • Loss of tools
      • by abstracting code into a 3rd party Template library, you lose access to mature tools that are common for languages like PHP, JS, etc. Twig, and templates like that may not have as mature tools.
    • Limited access to variables
    • More prone to Markup Errors
    • Does just one thing, granted well however limited
  • Native Languages for layout
    • Can add programming complexity
    • Access to more variables
    • Mutate state
    • Can pull off more complex layouts
    • Reminds me of Drupal Render Arrays AKA Array’s of DOOM!
    • Just don’t put imperative code in your views :)
      • Be mindful of the separation of concerns

Quotes

  • “Clean code always looks like it was written by someone who cares.” - Michael Feathers
  • “Leave the code better then you found it” What if we did this every time we added to code. - Borrowed from the guy who founded the Boy Scouts.

Sources

  1. Code Complete, Second Edition
  2. Templating languages: The hidden costs - Fun Fun Function
  3. JavaScript Cookbook, 2nd Edition