Programming as a writing genre

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

1

Your Speaker
 Professor

of Software Engineering.

 PhD

in EE (1995); Taught CE, CS and SE courses
 Certified Software Development Professional (2001)
 Teaching:
 Requirements,

project management, testing, design, programming,
quality assurance
 Computer architecture, Digital logic, Embedded Systems
 Leadership, Freshman Seminar, Professional Seminar, Civil War
 Currently:
 Deacon

MA in Pastoral Studies

Formation program in the Diocese of Erie

2

‘Creative’ Writing for
Software Engineers
 Self-Documenting

Code

 Maintainability

and readability
 More than coding standards
 Visual

Languages

 Organizing

writing

 Specification
 Standing

and Socio-Technical Systems

Committee Processes

Writing that creates something
3

Coding as written expression
Specialized,

goal-oriented writing

Goal:

make a computer system do
something of use

Means:

Coding

Formalized

grammar
Sequential Execution
Integrated Development Environment
(IDE)
Extensive Libraries
4

The Code-Writing Problem
 Imagine

writing a book for something

 With

multiple people writing
 People joining/leaving the team
 New pieces to be added to the manual
 Old pieces sometimes removed
 Multiple versions of the book being
published
 Needed:

Ability to:

 Modify

the book organization quickly
 Quickly teach new writers how and where
to integrate their stories
5

Elegant Code
(from Stackoverflow.com blog)
Elegant code is a combination of:
Correctness. IMHO no wrong code can truly be elegant.
Correctness
Succinctness. Less code means less to go wrong, less to
Succinctness
understand. Briefly and clearly expressed.
Readability. The easier it is to understand code, the easier to
Readability
maintain.
Performance. To a point. Prematurely optimized code cannot
Performance
truly be elegant.

6

Elegant Code cont.
(from Stackoverflow.com blog)
Elegant code is a combination of:
Standardized. Following the established standards of the
Standardized
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 it.  It's easy to label code that is
it
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,
elegant, and wrong"
7

Sample Problem
Write some code to
Do something of use…
Enter the the amountconvert ($XX.XX): 11.55 USD
Enter amount to to convert ($XX.XX): 11.55 USD
The a currency-conversion program that takes a
Developamount requested: $11.55 USD is also 11.55 USD.number
The amount requested: places), and a three-letter currency
(rounded to two decimal $11.55 USD is also 7.51 GBP.
The amount requested: $11.55 USD is
(e.g., “USD”) and converts to availablealso 10.97 CHF.
currencies. Manage
The amount requested: $11.55 USD is also 11.55 BSD.
conversions forrequested: $11.55 USDGBP, AUD, AUD. and
at least EUR, USD, is also 12.01 CAD
The amount
CHF. amount requested: $11.55 USD is also 11.90 CAD.
The
The amount requested: $11.55 USD is also 8.89 EUR.
8

Java Sample
Takes an <amount> and print six conversions…
public static void changeCurrency(float amount) {
System.out.println("The amount requested: ” +amount+
+(amount * 1)+ " BSD.");
+(amount * 1.03)+ " CAD.");
+(amount * 0.95)+ " CHF.");
+(amount * 1.04)+ " AUD.");
+(amount * 0.65)+ " GBP.");
+(amount * 0.77)+ " EUR.");

}
9

" is ”
" is ”
" is ”
" is ”
" is ”
" is ”

Java Sample – What’s Wrong

Repetitive: verbose;
hard to fix

Takes an <amount> and print six conversions…

+(amount * 1)+ " BSD.");
+(amount * 1.03)+ " CAD.");
+(amount * 0.95)+ " CHF.");
+(amount * 1.04)+ " AUD.");
+(amount * 0.65)+ " GBP.");
+(amount * 0.77)+ " EUR.");

}

Standards: embedded literals
10

" is ”
" is ”
" is ”
" is ”
" is ”
" is ”

Objects: Containers for behavior
Like 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
Unlike subsections
 Defined

in a manual

by classes, which are patterns for

objects;
 Defines both changeable information (data) and
behavior (operations) that modify or use that
data.
11

Repetitive: verbose;
hard to fix
Readability: What’s this?

Better Version

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

Readability: What are these?
//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);
12

Confounding Comments
 Commenting

Code – Why, why not?

 Why:

Easier to read, preserve ‘clear text’ message
 Why not: Often wrong or misleading, costly to maintain
 Process
 Use

to guide construction

 Product
 Use

Artifact:

Artifact:

to illustrate the code as written

13

Commented Code
public static void changeCurrency(float currencies;
// Print out the amount in the differentamount) {
// Code goes here
}
}
}

14

Control Structures
 Functional
 Define

Encapsulation

your own terms…

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 code
 Readable: Named for Use
 Performance: Optimized for reuse
 Standard: Follows conventions
15

Control Structures
 Conditional
 Used

Behavior

to avoid repeating code, ensure correct logic

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

16

Self-Documenting Code
 Name
 So

they make sense for their general use

 Name
 So

classes, structures & functions
objects and variables

they make sense for their specific use

 Heuristic:
 Can

it be misunderstood?
 Better name?
 Shorter is better
 Succinct, but no more succinct than necessary

17

Self-Documenting Code (1)
for (int i= 0; i< denom.length; i++) {
System.out.println(denom[i].conversionTranscript(amount));
}
}

Variable <i> - Descriptive? Specific? Concise?
NO

NO

18

YES

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

19

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

Yes

Yes

20

NO

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

for (CurrencyType currency : CurrencyType.values()) {
System.out.println(denom[currency.index()].conversionTranscript(am
ount));
}
}

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

Elegant Code
for (CurrencyType denom.length; i++) {
for (int i= 0; i< currency : CurrencyType.values()) {
System.out.println(denom[currency.index()].conversionTranscript(am
System.out.println(denom[i].conversionTranscript(amount));
ount));
}
}
}
}

 More

code… 
 Succinct… Less to remember… 
 Specific to problem… 
 Changes managed in one place…
 Reuseable pattern…
22

Writing Code: Summary
Like writing a policy manual; e.g., need to…
 Know

your purpose & audience (e.g. what you want it to do) first
 Understand how to express the intent (e.g., programing language)
 Write to achieve quality: correctness, readability, succinctness
 Break into small pieces
 Make easy to edit
Unlike writing a policy manual;
 Writing

to do, not just be
 Re-useable patterns for information &
behavior (classes)
 Re-useable operations (functions)
23

Programming as a writing genre

Recomendados

Recomendados

Mais conteúdo relacionado

Semelhante a Programming as a writing genre

Semelhante a Programming as a writing genre (20)

Mais de Stephen Frezza

Mais de Stephen Frezza (11)

Último

Último (20)

Programming as a writing genre