programming as a writing genre
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.TRANSCRIPT
![Page 1: Programming as a writing genre](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/1.jpg)
1
Writing Computer-eseSteve Frezza, Ph. D., C.S.D.P.
![Page 2: Programming as a writing genre](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/2.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/3.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/4.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/5.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/6.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/7.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/8.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/9.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/10.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/11.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/12.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/13.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/14.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/15.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/16.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/17.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/18.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/19.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/20.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/21.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/22.jpg)
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](https://reader033.vdocuments.mx/reader033/viewer/2022052601/559754db1a28ab005c8b4881/html5/thumbnails/23.jpg)
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)