23
1 Writing Computer-ese Steve Frezza, Ph. D., C.S.D.P.

Programming as a writing genre

Embed Size (px)

DESCRIPTION

From a talk given at the Computers & Writing Conference, June 2013. Discusses aspects of software engineering/computer science code construction and the similarities to writing in other genres.

Citation preview

Page 1: Programming as a writing genre

1

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

Page 2: Programming as a writing genre

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

Page 3: Programming as a writing genre

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

Page 4: Programming as a writing genre

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

Page 5: Programming as a writing genre

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

Page 6: Programming as a writing genre

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

Page 7: Programming as a writing genre

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

Page 8: Programming as a writing genre

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

Page 9: Programming as a writing genre

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.");

}

Page 10: Programming as a writing genre

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

Page 11: Programming as a writing genre

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.

Page 12: Programming as a writing genre

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

Page 13: Programming as a writing genre

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

Page 14: Programming as a writing genre

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));

}

Page 15: Programming as a writing genre

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

Page 16: Programming as a writing genre

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));}}

Page 17: Programming as a writing genre

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

Page 18: Programming as a writing genre

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

Page 19: Programming as a writing genre

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

Page 20: Programming as a writing genre

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

Page 21: Programming as a writing genre

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; }}

Page 22: Programming as a writing genre

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));}}

Page 23: Programming as a writing genre

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)