Programming as a writing genre

1

Writing Computer-eseSteve Frezza, Ph. D., C.S.D.P.

2

Your SpeakerProfessor of Software Engineering.

PhD in EE (1995); Taught CE, CS and SE coursesCertified Software Development Professional (2001)

Teaching:Requirements, project management, testing, design, programming,

quality assuranceComputer architecture, Digital logic, Embedded SystemsLeadership, Freshman Seminar, Professional Seminar, Civil War

Currently: MA in Pastoral StudiesDeacon Formation program in the Diocese of Erie

3

‘Creative’ Writing for Software Engineers

Self-Documenting CodeMaintainability and readabilityMore than coding standards

Visual LanguagesOrganizing writing

Specification and Socio-Technical SystemsStanding Committee Processes

Writing that creates somethingWriting that creates something

Coding as written expression

4

Specialized, goal-oriented writing

Goal: make a computer system do something of use

Means: CodingFormalized grammarSequential ExecutionIntegrated Development Environment

(IDE)Extensive Libraries

The Code-Writing Problem

Imagine writing a book for somethingWith multiple people writingPeople joining/leaving the teamNew pieces to be added to the manualOld pieces sometimes removedMultiple versions of the book being

published

Needed: Ability to:Modify the book organization quicklyQuickly teach new writers how and where

to integrate their stories

5

Elegant Code (from Stackoverflow.com blog)

Elegant code is a combination of:CorrectnessCorrectness. IMHO no wrong code can truly be elegant.SuccinctnessSuccinctness. Less code means less to go wrong, less to understand. Briefly and clearly expressed.ReadabilityReadability. The easier it is to understand code, the easier to maintain.PerformancePerformance. To a point. Prematurely optimized code cannot truly be elegant.

6

Elegant Code cont.(from Stackoverflow.com blog)

Elegant code is a combination of:StandardizedStandardized. Following the established standards of the platform or project. When given two equally elegant options, the one that is closest to the established standard is the best.Exactly the way I would do itExactly the way I would do it. It's easy to label code that is NOT how you would do it as "inelegant". Please don't do that - keep an open mind to different code.

"To every problem there is a solution that is simple, "To every problem there is a solution that is simple, elegant, and wrong"elegant, and wrong"

7

Write some code to

Do something of use…

Develop a currency-conversion program that takes a number (rounded to two decimal places), and a three-letter currency (e.g., “USD”) and converts to available currencies. Manage conversions for at least EUR, USD, GBP, AUD, CAD and CHF.

8

Enter the amount to convert ($XX.XX): 11.55 USD

The amount requested: $11.55 USD is also 11.55 USD.The amount requested: $11.55 USD is also 7.51 GBP.The amount requested: $11.55 USD is also 10.97 CHF.The amount requested: $11.55 USD is also 11.55 BSD.The amount requested: $11.55 USD is also 12.01 AUD.The amount requested: $11.55 USD is also 11.90 CAD.The amount requested: $11.55 USD is also 8.89 EUR.

Enter the amount to convert ($XX.XX):Enter the amount to convert ($XX.XX): 11.55 USD

Sample Problem

Java Sample

Takes an <amount> and print six conversions…

9

public static void changeCurrency(float amount) {System.out.println("The amount requested: ” +amount+ " is ” +(amount * 1)+ " BSD.");System.out.println("The amount requested: ” +amount+ " is ” +(amount * 1.03)+ " CAD.");System.out.println("The amount requested: ” +amount+ " is ” +(amount * 0.95)+ " CHF.");System.out.println("The amount requested: ” +amount+ " is ” +(amount * 1.04)+ " AUD.");System.out.println("The amount requested: ” +amount+ " is ” +(amount * 0.65)+ " GBP.");System.out.println("The amount requested: ” +amount+ " is ”

+(amount * 0.77)+ " EUR.");

}

Java Sample – What’s Wrong

Takes an <amount> and print six conversions…

10

public static void changeCurrency(float amount) {System.out.println("The amount requested: ” +amount+ " is ” +(amount * 1)+ " BSD.");System.out.println("The amount requested: ” +amount+ " is ” +(amount * 1.03)+ " CAD.");System.out.println("The amount requested: ” +amount+ " is ” +(amount * 0.95)+ " CHF.");System.out.println("The amount requested: ” +amount+ " is ” +(amount * 1.04)+ " AUD.");System.out.println("The amount requested: ” +amount+ " is ” +(amount * 0.65)+ " GBP.");System.out.println("The amount requested: ” +amount+ " is ”

+(amount * 0.77)+ " EUR.");

}

Repetitive: verbose;hard to fix

Standards: embedded literals

Objects: Containers for behavior

11

LikeLike subsections in a manual:Manual: one (sub)section defines/illustrates one ‘thing’ well.E.g., in a policy manual, all the rules pertaining to xyz policy should

be in that subsection, not scattered elsewhere in the document.Only one place to change that policy

UnlikeUnlike subsections in a manualDefined by classes, which are patterns for

objects;Defines both changeable information (data) and

behavior (operations) that modify or use that data.

Better Version

public static void changeCurrency(float amount) {System.out.println(BSD.conversionTranscript(amount));

System.out.println(CAD.conversionTranscript(amount));

System.out.println(CHF.conversionTranscript(amount));

System.out.println(AUD.conversionTranscript(amount));

System.out.println(GBP.conversionTranscript(amount));

System.out.println(EUR.conversionTranscript(amount));

}

12

Readability: What are these?

Readability: What’s this?

//Create a converter object for each of the currencies:private static Converter EUR = new Converter("EUR",0.77);private static Converter CAD = new Converter("CAD", 1.03);private static Converter AUD = new Converter("AUD", 1.04);private static Converter BSD = new Converter("BSD", 1.0);private static Converter CHF = new Converter("CHF", 0.95);private static Converter GBP = new Converter("GBP", 0.65);

Repetitive: verbose;hard to fix

Confounding Comments

Commenting Code – Why, why not?Why: Easier to read, preserve ‘clear text’ messageWhy not: Often wrong or misleading, costly to maintain

Process Artifact:Use to guide construction

Product Artifact:Use to illustrate the code as written

13

Commented Code

// Print out the amount in the different currencies;

public static void changeCurrency(float amount) {

// Code goes here

}

14

// Print out the amount in the different currencies;

public static void changeCurrency(float amount) {System.out.println(BSD.conversionTranscript(amount));

System.out.println(CAD.conversionTranscript(amount));

System.out.println(CHF.conversionTranscript(amount));

System.out.println(AUD.conversionTranscript(amount));

System.out.println(GBP.conversionTranscript(amount));

System.out.println(EUR.conversionTranscript(amount));

}

public static void changeCurrency(float amount) {System.out.println(BSD.conversionTranscript(amount));

System.out.println(CAD.conversionTranscript(amount));

System.out.println(CHF.conversionTranscript(amount));

System.out.println(AUD.conversionTranscript(amount));

System.out.println(GBP.conversionTranscript(amount));

System.out.println(EUR.conversionTranscript(amount));

}

Control Structures

Functional EncapsulationDefine your own terms…

15

public String conversionTranscript( double valueInUSD) {String amountString = String.format("The amount requested: $%.2f USD is also %.2f ", valueInUSD, convertFromUSD(valueInUSD));return amountString + currencyCode + ".";}

Correct: Does one thing well Succinct: Short, focused, no extraneous codeReadable: Named for Use Performance: Optimized for reuseStandard: Follows conventions

public static void changeCurrency(float amount) {System.out.println(BSD.conversionTranscript(amount));

System.out.println(CAD.conversionTranscript(amount));

System.out.println(CHF.conversionTranscript(amount));

System.out.println(AUD.conversionTranscript(amount));

System.out.println(GBP.conversionTranscript(amount));

System.out.println(EUR.conversionTranscript(amount));

}

Control Structures

Conditional BehaviorUsed to avoid repeating code, ensure correct logic

16

public static void changeCurrency(float amount, Denomination[] denom) {for (int index = 0; index < denom.length; index++) {System.out.println(denom[index].conversionTranscript(amount));}}

Self-Documenting Code

Name classes, structures & functionsSo they make sense for their general use

Name objects and variablesSo they make sense for their specific use

Heuristic:Can it be misunderstood?Better name?Shorter is betterSuccinct, but no more succinct than necessary

17

Self-Documenting Code (1)

18

public static void changeCurrency(float amount, Denomination[] denom) {for (int i= 0; i< denom.length; i++) {System.out.println(denom[i].conversionTranscript(amount));}}

Variable <i> - Descriptive? Specific? Concise?

NO NO YES

Self-Documenting Code (2)

19

public static void changeCurrency(float amount, Denomination[] denom) {for (int index = 0; index < denom.length; index++) {System.out.println(denom[index].conversionTranscript(amount));}}

Variable <index> - Descriptive? Specific? Concise?

A little NO Sort-of

Self-Documenting Code (3)

20

public static void changeCurrency(float amount, Denomination[] denom) {for (int denomIndex = 0; denomIndex < denom.length; denomIndex++) {System.out.println(denom[denomIndex].conversionTranscript(amount));}}Variable <index> - Descriptive? Specific? Concise?

Yes Yes NO

Self-Documenting Code (4)

21

public static void changeCurrency(float amount, Denomination[] denom) {for (CurrencyType currency : CurrencyType.values()) {System.out.println(denom[currency.index()].conversionTranscript(amount));}}

Variable <currency> - Descriptive? Specific? Concise?Yes Yes Yes

public enum CurrencyType {USD(0), EUR(1), CAD(2), AUD(3), BSD(4), CHF(5), GBP(6);private int typeIndex;CurrencyType (int index) { typeIndex = index; }public int index() { return typeIndex; }}

Elegant Code

22

More code… Succinct… Less to remember… Specific to problem… Changes managed in one place…

Reuseable pattern…

public static void changeCurrency(float amount, Denomination[] denom) {for (int i= 0; i< denom.length; i++) {System.out.println(denom[i].conversionTranscript(amount));}}

public static void changeCurrency(float amount, Denomination[] denom) {for (CurrencyType currency : CurrencyType.values()) {System.out.println(denom[currency.index()].conversionTranscript(amount));}}

Writing Code: Summary

23

LikeLike writing a policy manual; e.g., need to… Know your purpose & audience (e.g. what you want it to do) firstUnderstand how to express the intent (e.g., programing language)Write to achieve quality: correctness, readability, succinctnessBreak into small piecesMake easy to edit

UnlikeUnlike writing a policy manual; Writing to do, not just beRe-useable patterns for information &

behavior (classes)Re-useable operations (functions)