blurredbits/craftingcode.md

## craftingcode.md

      
    Raw
  

              craftingcode.md
            
          
    Crafting Code

Here's the thing. Computers are nothing more than really fast light switches. On & off millions of times per second. All it cares about is ones & zeroes.
So when it comes to code, and more specifically crafting code, who are we really writing code for?
We're writing it for ourselves, our teammates or our customers - basically other humans. We're using code to express ideas, human ideas in terms of a computer language. As developers, we're tasked with creating sets of instructions to be carried out by our dumb servants to execute these ideas.
If the computer doesn't particularly care about code (other than a clean compile) - what are some of the tools we can use to craft our code for human consumption?
###Consistency
Imagine you're reading a news article and you spot a mis-spelled word.
What happens? The information that is trying to be conveyed is suddenly lost. All your attention is drawn to the mis-spelling.
Same thing happens in code.
Odd spacing, weird idents and misplaced code interrupt your train of thought as a programmer. Instead of cleary communicating an idea - inconsistent code creates a mental hurdle. When working in a team, negotiate a style guide - and do your best to follow it.
But consistency goes deeper than just a style guide. Opinionated frameworks usually have an idiomatic way of doing things. Learn these techniques and follow them.
Finally, even when following idiomatic patterns within a framework, as a programmer you'll often see patterns within code. Perhaps you recognize a common pattern (e.g. template) that a code base is using. Ask yourself, is it worth breaking that pattern for an update? Even when you spot something that could be implemented better - Usually, it's best to follow the existing pattern. Make notes and propose alternatives - but consider the context of the existing codebase and the mental jump another programmer might have to make in the future.
###Reducing Complexity
Most programmers have learned that short, clean bits of code are easier to maintain. One simple rule is that once you get over 5 lines of code within a method, consider creating an additional method. DRY up your code and constantly be on the lookout for abstractions.
Like consistency, complexity goes a deeper as well. As our skills as developers grow, we start to find shortcuts - clever little hacks in the language - but just because you can, does that mean you should?
For example, consider meta-programming. It's a truly powerful feature of the Ruby programming language - but it also takes significant cognitive load to understand how it is being used within a codebase. Carefully consider if the increased complexity outweigh the potential benefits.
Sometimes we introduce unneeded complexity in the name of expendiency. Consider the variable e. In JavaScript it's often used to represent an event. By itself, this practice usually isn't troublesome. However, when the practice is carried to additional areas of the code base, and short named variables are used everywhere - suddenly, variables like b, i, etc. have no context. For both complexity and consistency, using descriptive, full variable names saves future frustration.
Along the same lines, magic numbers inadvertenly introduce complexity and break flow. Declaring a descriptive constant name and assigning the number to that constant takes just a couple of extra keystrokes, and creates future context for the next programmer.
###Comments
There's an old saying amongst programmers, "Comments are just lies waiting to happen". Often they are just that. However, when used judiciously - comments can provide valuable information to a human reader. What are some good use cases? Well, I would argue that anytime you are going to do something complex or break consistency - that's a perfect place for multiple comments. Comments can also be used as placeholders - detailing areas of functionality that will be eventually implemented.
Unless defined in a style guide, it's also a good idea to put your initials and a timestamp in any comment. This will give your future a reader an idea of the age of the comment and the original author.
Comments can also be used to define areas of code functionality. Used in conjunction with whitespace, comments can help define placeholders for functionality. For example:
class CaseRepositionsController < ApplicationController
  
  #-------------------------------------------------
  # Configuration
  #-------------------------------------------------
  
  before_filter :load_instance
  
  
  #-------------------------------------------------
  # Public methods
  #-------------------------------------------------
  
  #========== UPDATE ===============================
  
  def edit; end
  
  
  def update
    @case_reposition.attributes = case_params
   
    if @case_reposition.save
      redirect_to needs_path
    else
      flash.now[:error] = t('scaffolds.generic.flash.error')
      render :edit
    end
  end


  #-------------------------------------------------
  # Private methods
  #-------------------------------------------------
   

I can hear the screams now - "The code should define the functionality! Comments aren't needed!". This brings me around to my original point - code is for humans not computers. Anything we can do as programmers to clearly communicate our ideas and intent helps the process.
###Conclusion
When crafting code consider your audience: your team members, your customers, even your future self. Stay consistent, reduce complexity whenever possible and document your code with well-placed comments. You'll be well on your way towards towards crafting easily understandable and maintable code.