Adventures in Software Craftsmanship

Day 1 - September 14, 2015

Introduction

Daniel Yanos

July 2014

EDS - Retail

Silver Surfer - Big Data

Jason Riddle

Feb 2015

COS - Card Tech

Grayskull - CICD Engineer

What is "Software Craftsmanship?"

A craftsman or artisan is a skilled manual worker who makes items that may be functional or strictly decorative.

The Art of Software

Writing code is similar to painting a picture. A programmer who writes clean code is an artist who can guide a blank screen through a series of transformations until it is an elegantly coded system.

• ​Easy to recognize a good painting
• Hard to paint a good picture

Programmers are authors – responsible for communicating well with their readers.

• You write for readers who will judge your effort and skill
• The ratio spent reading vs. writing code is usually at least 10:1

​

The Science of Software

What do these have in common?

• UI/UX Design
• Animating a Movie
• Engineering a Bridge
• Studying Quantum Entanglement
• Programming

Scientific Method

Science

Ask a Question

Background Research

Construct Hypothesis

Test with Experiment

Analyze Data &

Draw Conclusions

Communicate Results

The Science of Software

Why is it helpful to think of software as a craft? 

• Effective way to transition from the college mindset of software development to a professional mindset
• Aligns with Capital One's objective of becoming a leading technology company
• Important for improving your technical skills and succeeding in the workplace

From Journeyman to Master

As a student:

• Solve it
• Test it
• Fix it
• Turn it in
• Forget about it

As a professional:

• Solve it
  • Make it easy to understand
  • Make it easy to use
  • Make it easy to change
• Test it
• Fix it
• Review it
• Commit it
• Test it
• Release it
• Support it

Mantras of a Software Craftsman

• Broken windows
  • ​One broken window, left un-repaired, instills in the community a sense of abandonment.
• Boy Scout rule
  • ​"Leave the campground cleaner than you found it."
• Tests are your parachute
  • ​Keep them free of holes and obstructions.

Your Knowledge Portfolio

Your knowledge and experience are your most important professional assets.

Unfortunately, they're expiring assets.

• Invest regularly
• Diversify
• Manage risk
• Buy low, sell high
• Review and rebalance

Expand your knowledge portfolio regularly; not only with technical expertise but also Capital One expertise.

Code Reading Competition

public void fireLoadSummaryEventAction(ActionRequest request, ActionResponse response) {
    ApplicationObject appObject = null;
    String token = null;
    EPFContext context = EPFContextContainer.getcurrentContext().get();
    String correlationID = context.getCorrelationId();
    try {
        try {
            //retrieve token
            HttpServletRequest httpServletReq = (HttpServletRequest) request.getAttribute("javax.servlet.request");
            HttpSession session = httpServletReq.getSession();
            token = (String)session.getAttribute("eosToken");
            //retrieve composite object and store in cache
            appObject = creditcardappdataserviceclient.retrieveApplicationData(token);			
            //store composite object in cache
            UserContext userContext = cache.getCachedUserContext(correlationID, appObject);	
        } catch (JaxWsSoapFaultException sfe) {
            logger.error("SOAP Fault on composite object retreival");
            appObject = new ApplicationObject();
            //set statCd to soap fault, for data retrieval audit logging
            setStatCd(appObject,STATUS_CODE_RTM_SOAP_FAULT);
            //audit data retrieval status		
            auditLogUtil.auditEOSEvent(token, auditLogUtil.AUDIT_EVENT_APP_DATA_RETRIEVAL_NAME, appObject, auditLogUtil.AUDIT_EVENT_STATUS_SOAP_FAULT);
            //set statCd to "data not retrieved", for soft decline audit logging
            setStatCd(appObject,STATUS_CODE_DATA_RETRIEVAL_FAILED);
            throw new EPFSystemException("SOAP Fault", sfe);
        } catch (Exception e) {
            logger.error("Error retrieving or caching composite object. " + e.getMessage());
            if (appObject == null ) {
                appObject = new ApplicationObject();
            }
            //set statCd to general error, for data retrieval audit logging
            setStatCd(appObject,STATUS_CODE_GENERAL_DATA_RETRIEVAL_ERROR);
            //audit data retrieval status
            auditLogUtil.auditEOSEvent(token, auditLogUtil.AUDIT_EVENT_APP_DATA_RETRIEVAL_NAME, appObject, auditLogUtil.AUDIT_EVENT_STATUS_ERROR);
            //set statCd to "data not retrieved", for soft decline audit logging
            setStatCd(appObject,STATUS_CODE_DATA_RETRIEVAL_FAILED);
            throw new EPFBusinessException(new EPFMessage(e.getMessage()));
        }
        //audit data retrieval status
        auditLogUtil.auditEOSEvent(token, auditLogUtil.AUDIT_EVENT_APP_DATA_RETRIEVAL_NAME, appObject, null);
        //check for an error/warning in stat code
        if (findStatusError(appObject)) {
            String errorCode = getStatCode(appObject);
            String errorMsg = "A status of error or warning was returned by RTM.  RTM Status code:" + errorCode; 
            logger.warn(errorMsg);
            //set statCd to "data not retrieved", for soft decline audit logging
            setStatCd(appObject,STATUS_CODE_DATA_RETRIEVAL_FAILED);
            throw new EPFBusinessException(new EPFMessage(errorCode));
        }
        //check if token expired
        verifyTokenNotExpired(appObject);
        //verify the disclosure can be built
        buildDisclosure(appObject);
        //update disclosure flag
        invokeDisclosureFlagUpdate(appObject, token);
        //fetch values required by DSD portlets
        EnrollmentEvent sspEvent  = getUserInfo(appObject);
        //fire JSR event to invoke DSD portlet to receive required info
        QName qname2 = new QName("http://www.capitalone.com/sspEvent","sspEvent");
        response.setEvent(qname2, sspEvent);
        //fire JSR event to invoke summary portlet controller
        QName qname = new QName("http://eos.capitalone.com","loadResultsCustomEvent");
        response.setEvent(qname, null);
        //fire WLP event for portal page change
        QName qname1 = new QName("http://eos.capitalone.com","pageChangeEvent");
        response.setEvent(qname1, null);
        response.setRenderParameter("myaction", "done");
    } catch (Exception e) {
        logger.error("Error preparing to display results", e);
        //audit soft approval (display of error page)
        auditLogUtil.auditEOSEvent(token, auditLogUtil.AUDIT_EVENT_APP_SOFT_DECLINE_NAME, appObject, auditLogUtil.AUDIT_EVENT_STATUS_NOT_PROVIDED);
        //set render param to invoke error page
        response.setRenderParameter("myaction", "errorRenderMapping");
    }
}	

The Perils of Messy Code

Mess builds, productivity of team decreases

Under pressure, the team makes more messes

Entropy - The amount of disorder in a system. When disorder increases in software, it is called "code rot".

The only way to develop quickly and meet deadlines is to keep the code as clean as possible at all times.

http://xkcd.com/844/

What is messy code?

What is clean code?

if (appObject.isDsclsrOnlineRequiredInd() || appObject.isDsclsrCreditScoreRequiredInd()) {
    if (appObject.isDsclsrOnlineRequiredInd()) {
        // Pull account disclosure
        setDisclosureVariableFromContent(AOD, aodVariableReplacer,
            appObject.getDecisionedOfferID(), model, evalContext);
    }
            
    if (appObject.isDsclsrCreditScoreRequiredInd() && appObject.getMinCreditScore() != null 
            && appObject.getMinCreditScore().getBureauCode()!=null) {
        // Pull credit disclosure
        if(appObject.getMinCreditScore().getBureauCode().equals("")){
            setDisclosureVariableFromContent(CSD, csdVariableReplacer,
               NO_HIT_KEY , model, evalContext);
        }else{
            setDisclosureVariableFromContent(CSD, csdVariableReplacer,
                appObject.getMinCreditScore().getBureauCode() , model, evalContext);
        }
    }
}

if (appObject.getApplicant() != null && appObject.getApplicant().get(0) != null ) { 
    userInfo.setFirstName(appObject.getApplicant().get(0).getFirstName());
    userInfo.setLastName(appObject.getApplicant().get(0).getLastName());			
    userInfo.setLangCode(appObject.getApplicant().get(0).getLangCode());
    userInfo.setSsoId(null);
    userInfo.setUserId(appObject.getApplicant().get(0).getCustomerID());
			
    if (appObject.getApplicant().get(0).getEmailAddresses() != null  &&
            appObject.getApplicant().get(0).getEmailAddresses().size() > 0) {	
        userInfo.setEmailAddress(appObject.getApplicant().get(0).getEmailAddresses().get(0));
    }	
}

Coupling and Cohesion

With tightly coupled systems:

1. A change in one module forces changes in others
2. Modules are harder to reuse
3. Modules are harder to test

With low cohesion systems:

1. Modules are complex with more operations
2. Modules are less maintainable and harder to work with

Coupling is a measure of how closely connected two routines or modules are.

Cohesion is a measure of how strongly related each piece of functionality is.

Coupling and Cohesion have an inverse relationship

Law of Demeter

1. Object A can call a method of object B but should not "reach through" B to acquire a reference to object C.
2. A method m of class A may only invoke methods on:
   1. A itself
   2. m's parameters
   3. Objects instantiated within m
   4. A's direct instance objects
   5. A global variable, accessible by A, in the scope of m

Since objects are less dependent on the internal structure of other objects, classes can be changed without reworking their callers.

Orthogonality

• When components are highly interdependent, there is no such thing as a quick, local fix.

• Orthogonal software provides increased productivity and decreased risk because developers never have to worry about side-effects of making changes.

• Orthogonal components are easier to swap meaning less dependence on a specific library or vendor.

Two or more modules are orthogonal if

changes in one do not affect the other.

The Evils of Duplication

• Requirements, understanding, and environments change. Your code will need to change with it.

• It's not a matter of if you'll remember, but when you'll forget.

DRY - Don't Repeat Yourself

• Imposed duplication
• Inadvertent duplication
• Impatient duplication
• Inter-developer duplication

SOLID Design Principles

• Single Responsibility Principle (SRP)

• Open/Closed Principle (OCP)

• Liskov Substitution Principle (LSP)

• Interface Segregation Principle (ISP)

• Dependency Inversion Principle (DIP)

Single Responsibility Principle

• The single responsibility should be entirely encapsulated by its context

• A unit of code should have only one reason to change

• Keeps a class focused (high cohesion)

• Lowers coupling

A class or module should be defined by one, and only one, responsibility.

public class AreaCalculator {

    public double pi = Math.PI;

    public double calculateArea(Shape[] shapes) {
        double area = 0;

        for (Shape shape : shapes) {
            if (shape instanceof Rectangle) {
                Rectangle rectangle = (Rectangle) shape;
                area += rectangle.getWidth() * rectangle.getHeight();
            } else {
                if (shape instanceof Circle) {
                    Circle circle = (Circle) shape;
                    area += circle.getRadius() * circle.getRadius() * pi;
                }
            }
        }
    
        return area;
    }
}

Open/Closed Principle

• Allows its behavior to be extended without modifying its source code

• Utilizes inheritance and polymorphism

• Promotes code reusability

• Prevents unnecessary code reviews and testing

Software entities should be open for extension, but closed for modification.

    public class Blah {
    
        private HashMap<String, String> map;
    
        public ArrayList<String> getUniqueValues(TreeMap<Integer, String> map) {
            . . .
        }
    
    }
    
    
    
    
    public class Square extends Rectangle {
    
        public void setHeight(int height) { . . . }
    
        public void setWidth(int width) { . . . }
    
    }

Liskov Substitution Principle

Objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program.

Always reference the most abstract type that provides all the required methods.

Subclass implementations can be swapped out later.

​Multiple implementations can be accommodated by a library.

private Map<String, Integer> blah;
private Map<String, Integer> gah;

public BlahGah() {
    blah = new HashMap<String, Integer>();
    gah = new TreeMap<String, Integer>();
}

public static <T> void sort(List<T> list, Comparator<? super T> c) { . . . }

public interface Bank {

    public void addAccount(Account account);

    public Account getAccount(String accountNumber);

    public void deposit(String accountNumber, double amount);

    public void withdraw(String accountNumber, double amount);

    public void applyInterest(String accountNumber);

    public void applyFee(String accountNumber, double fee);
}

Interface Segregation Principle

Interface-based design:

• The foundation of APIs
• Design from the outside in
• Write the interfaces first
• Practice TDD

Keep interfaces focused and segregated by purpose. Many client-specific interfaces are better than one general purpose interface.

DIP violation examples

class GameBoard {

    private List<MonopolyPlayer> players;
    private Dice dice;
}

class MonopolyPlayer implements Player {

    void playTurn() {
        Dice di = GameBoard.getdice(); // or GameBoard.DICE [Test dependency]
        int numMoves = di.roll();
        . . .
    }
}


interface Dice {

    public int roll();

}

Dependency Inversion Principle

• Separate high-level and low-level components into separate packages

• Interfaces belong in high-level package, implementations in low-level

• Keep consistent and developer friendly

• Allows for swapping implementations

• Promotes code encapsulation with flexibility

1. High-level modules should not depend on low-level modules.
2. Abstractions should not depend on details.

class Player {

    void playTurn(Dice di) {
        int numMoves = di.roll(); // or 'inject' numMoves if 'di' (analogy) is not needed further
        . . .
    }
}

@Repository
public class UserDao extends JdbcDaoSupport {

    @InjectLogger
    private Logger logger;

    @Inject
    public UserDao(final DataSource dataSource) {
        setDataSource(dataSource);
    }
}


@Configuration
public class SpringConfig {

    @Bean
    public DataSource dataSource() {
        DataSource dataSource = new BasicDataSource();
        dataSource.setDriverClassName("org.postgresql.Driver");
        dataSource.setUrl("jdbc:postgresql://localhost:5432/mydb");
        dataSource.setUsername("username");
        dataSource.setPassword("password");
        return dataSource;
    }
}

   public String generateMessage(StreamMessageContext ctx, Object... data) {
        int size = ((data == null) ? 1 : data.length + 1);
        
        // serialize each object
        int i = 1;
        String[] jsonEntries = new String[size];
        jsonEntries[0] = DataConversionSupport.serializeToJsonString(ctx);
        for (Object datum : data) {
            jsonEntries[i] = DataConversionSupport.serializeToJsonString(datum);
            ++i;
        }
        
        // then aggregate all the serializations together
        StringBuilder sb = new StringBuilder();
        sb.append('{').append('\"').append(ctx.getClass().getSimpleName()).append("\":").append(jsonEntries[0]); // the key
        for (int j = 0; j < i - 1; ++j) {
            sb.append(',\"').append(data[j].getClass().getSimpleName()).append("\":"); // item name
            sb.append(jsonEntries[j + 1]); // item json
        }
        sb.append('}');
        return sb.toString();
    }
    
    public String generateMessage(StreamMessageContext ctx, String[] dataKeys, Object... data) {
        int size = ((data == null) ? 1 : data.length + 1);
        
        // serialize each object
        int i = 1;
        String[] jsonEntries = new String[size];
        jsonEntries[0] = DataConversionSupport.serializeToJsonString(ctx);
        for (Object datum : data) {
            jsonEntries[i] = DataConversionSupport.serializeToJsonString(datum);
            ++i;
        }
        
        // build up keys
        String[] keys = processDataKeys(dataKeys, data);
        
        // then aggregate all the serializations together
        StringBuilder sb = new StringBuilder();
        sb.append('{').append('\"').append(ctx.getClass().getSimpleName()).append("\":").append(jsonEntries[0]); // the key
        for (int j = 0; j < i - 1; ++j) {
            sb.append(',\"').append(keys[j]).append("\":"); // item name
            sb.append(jsonEntries[j + 1]); // item json
        }
        sb.append('}');
        return sb.toString();
    }

Interface Design

Capital One is doing pretty well in the banking industry, but Uncle Rich has decided we need to diversify our product offerings, and he's made the decision to go into the lucrative business of opening PB&J sandwich shops (that's right, we're only selling peanut butter and jelly sandwiches). He's put you in charge of designing the backend system that allow users to place orders for custom sandwiches. Being the software craftsman that you are, you know we need to design this system from the outside in - that means creating interfaces for our sandwich shop before we come up with concrete implmentations. 

Code Conventions

Follow the Rules

Actually, follow the Principles

Rules are attempts to standardize agreement of how we follow Principles.

Rules change over time, teams, and environments.

The underlying Principles stay the same.

Breaking rules can be fine but breaking principles will cost down the line.

Rule: Don't tell lies

Principle: Honesty and Kindness

Naming Conventions

Function Conventions

• Small
• Do only one thing
• One level of abstraction per function
• Descriptive names

• Minimal parameters
• Don't pass codes
• Don't return null

• Verbs not nouns

Commenting Conventions

"Programs must be written for people to read and only incidentally for machines to execute" - Hal Abelson

• The only "comment" guaranteed to be accurate is the code its self
• Comments have to be maintained and updated same as the code
• The more complex the comments are, the more likely they are to be wrong or out of date

The best solution is to write easily comprehensible code.

Good Comments

Code can't explain why the program is being written, and the rationale for choosing this or that method. Code cannot discuss reasons certain alternative approaches were taken.

Comments are best used to provide contextual information that makes it easier to understand the code.

• How the code fits into the big picture
• Why this methodology was chosen and why others were rejected
• Code is written to solve a problem. Describe how your code solves the problem and why it is better than the alternatives
• Warning of consequences

Bad Comments

Single line comments are usually unnecessary and should only be used if the operation is complex.

j = j + 1; //Increment j
int a = c * 100; //convert to cents
double avg = a / n; //average cents per customer

int totalCents = totalDollars * 100;
double averageCentsPerCustomer = totalCents / customerCount;

Instead of writing comments that are designed to make code more readable, rewrite the code.

BAD

GOOD

Do not release with TODOs or commented-out code 

    /*
    * Purpose: Check the status of the composite object for errors or warnings.
    */
    private boolean findStatusError(ApplicationObject appObject) {
        if (appObject == null ||
            appObject.getStatusListAppDataInq() == null ||
            appObject.getStatusListAppDataInq().size() == 0 ||
            appObject.getStatusListAppDataInq().get(0) == null ||
            appObject.getStatusListAppDataInq().get(0).getSeverity() == null ||
            (appObject.getStatusListAppDataInq().get(0).getSeverity().name()).equals(Severity.ERROR.toString()) ||
            (appObject.getStatusListAppDataInq().get(0).getSeverity().name()).equals(Severity.WARNING.toString()) ||
            (appObject.getStatusListAppDataInq().get(0).getSeverity().name()).equals(Severity.FAULT.toString()))
                return true;
            else
                return false;
        }
    }

Code Formatting Conventions

• Density
• Distance
• Order

Horizontal formatting

• Density
• Alignment
• Indentation

Vertical formatting

Code Formatting Conventions

https://google-styleguide.googlecode.com/svn/trunk/javaguide.html

http://lars-lab.jpl.nasa.gov/JPL_Coding_Standard_Java.pdf

Common rules:

• Documentation (JavaDoc) conventions
• Upper-case class names; camel-case variable names
• New line after conditionals; always using braces
• One variable per declaration
• No chained method calls
• Store common references for reuse
• Encapsulate and use positive conditionals
• Declare abstract type, instantantiate implementation

Follow team and company rules

Exception Conventions

• Fail fast
• Catch specific exceptions
• Catch only when it can be handled in a meaningful way
• Use exceptions rather than return codes
• Do not use exceptions for control flow
• Provide context with exceptions
  • Informative error messages
  • Failed operation and values