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...
‘Creative’ Writing for
Software Engineers
 Self-Documenting

Code

 Maintainability

and readability
 More than coding ...
Coding as written expression
Specialized,

goal-oriented writing

Goal:

make a computer system do
something of use

Me...
The Code-Writing Problem
 Imagine

writing a book for something

 With

multiple people writing
 People joining/leaving...
Elegant Code
(from Stackoverflow.com blog)
Elegant code is a combination of:
Correctness. IMHO no wrong code can truly be...
Elegant Code cont.
(from Stackoverflow.com blog)
Elegant code is a combination of:
Standardized. Following the establishe...
Sample Problem
Write some code to
Do something of use…
Enter the the amountconvert ($XX.XX): 11.55 USD
Enter amount to to ...
Java Sample
Takes an <amount> and print six conversions…
public static void changeCurrency(float amount) {
System.out.prin...
Java Sample – What’s Wrong

Repetitive: verbose;
hard to fix

Takes an <amount> and print six conversions…

public static ...
Objects: Containers for behavior
Like subsections

in a manual:

 Manual:

one (sub)section defines/illustrates one ‘thi...
Repetitive: verbose;
hard to fix
Readability: What’s this?

Better Version

public static void changeCurrency(float amount...
Confounding Comments
 Commenting

Code – Why, why not?

 Why:

Easier to read, preserve ‘clear text’ message
 Why not: ...
Commented Code
public static void changeCurrency(float currencies;
// Print out the amount in the differentamount) {
Syste...
Control Structures
 Functional
 Define

Encapsulation

your own terms…

public String conversionTranscript( double value...
Control Structures
 Conditional
 Used

Behavior

to avoid repeating code, ensure correct logic

public static void chang...
Self-Documenting Code
 Name
 So

they make sense for their general use

 Name
 So

classes, structures & functions
obj...
Self-Documenting Code (1)
public static void changeCurrency(float amount,
Denomination[] denom) {
for (int i= 0; i< denom....
Self-Documenting Code (2)
public static void changeCurrency(float amount,
Denomination[] denom) {
for (int index = 0; inde...
Self-Documenting Code (3)
public static void changeCurrency(float amount,
Denomination[] denom) {
for (int denomIndex = 0;...
Self-Documenting Code (4)
public enum CurrencyType {
USD(0), EUR(1), CAD(2), AUD(3), BSD(4), CHF(5), GBP(6);
private int t...
Elegant Code
public static void changeCurrency(float amount,
public static void changeCurrency(float amount,
Denomination[...
Writing Code: Summary
Like writing a policy manual; e.g., need to…
 Know

your purpose & audience (e.g. what you want it...
Upcoming SlideShare
Loading in …5
×

Programming as a writing genre

319 views

Published on

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.

Published in: Education, Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
319
On SlideShare
0
From Embeds
0
Number of Embeds
8
Actions
Shares
0
Downloads
3
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Programming as a writing genre

  1. 1. Writing Computer-ese Steve Frezza, Ph. D., C.S.D.P. 1
  2. 2. 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
  3. 3. ‘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
  4. 4. 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
  5. 5. 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
  6. 6. 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
  7. 7. 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
  8. 8. 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
  9. 9. 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."); System.out.println("The amount requested: ” +amount+ +(amount * 1.03)+ " CAD."); System.out.println("The amount requested: ” +amount+ +(amount * 0.95)+ " CHF."); System.out.println("The amount requested: ” +amount+ +(amount * 1.04)+ " AUD."); System.out.println("The amount requested: ” +amount+ +(amount * 0.65)+ " GBP."); System.out.println("The amount requested: ” +amount+ +(amount * 0.77)+ " EUR."); } 9 " is ” " is ” " is ” " is ” " is ” " is ”
  10. 10. Java Sample – What’s Wrong Repetitive: verbose; hard to fix Takes an <amount> and print six conversions… public static void changeCurrency(float amount) { System.out.println("The amount requested: ” +amount+ +(amount * 1)+ " BSD."); System.out.println("The amount requested: ” +amount+ +(amount * 1.03)+ " CAD."); System.out.println("The amount requested: ” +amount+ +(amount * 0.95)+ " CHF."); System.out.println("The amount requested: ” +amount+ +(amount * 1.04)+ " AUD."); System.out.println("The amount requested: ” +amount+ +(amount * 0.65)+ " GBP."); System.out.println("The amount requested: ” +amount+ +(amount * 0.77)+ " EUR."); } Standards: embedded literals 10 " is ” " is ” " is ” " is ” " is ” " is ”
  11. 11. 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
  12. 12. Repetitive: verbose; hard to fix Readability: What’s this? 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)); } 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
  13. 13. 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
  14. 14. Commented Code public static void changeCurrency(float currencies; // Print out the amount in the differentamount) { System.out.println(BSD.conversionTranscript(amount)); public static void changeCurrency(float amount) { System.out.println(BSD.conversionTranscript(amount)); System.out.println(CAD.conversionTranscript(amount)); // Code goes here System.out.println(CHF.conversionTranscript(amount)); System.out.println(CAD.conversionTranscript(amount)); } System.out.println(AUD.conversionTranscript(amount)); System.out.println(CHF.conversionTranscript(amount)); System.out.println(GBP.conversionTranscript(amount)); System.out.println(AUD.conversionTranscript(amount)); System.out.println(EUR.conversionTranscript(amount)); System.out.println(GBP.conversionTranscript(amount)); } System.out.println(EUR.conversionTranscript(amount)); } 14
  15. 15. 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
  16. 16. Control Structures  Conditional  Used Behavior to avoid repeating code, ensure correct logic public static void changeCurrency(float amount, public static void changeCurrency(float amount) { Denomination[] denom) { System.out.println(BSD.conversionTranscript(amount)); for (int index = 0; index < denom.length; index++) { System.out.println(CAD.conversionTranscript(amount)); System.out.println(denom[index].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)); } 16
  17. 17. 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
  18. 18. Self-Documenting Code (1) 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 18 YES
  19. 19. Self-Documenting Code (2) 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 19
  20. 20. Self-Documenting Code (3) 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 20 NO
  21. 21. Self-Documenting Code (4) 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; } } public static void changeCurrency(float amount, Denomination[] denom) { for (CurrencyType currency : CurrencyType.values()) { System.out.println(denom[currency.index()].conversionTranscript(am ount)); } } Variable <currency> - Descriptive? Specific? Concise? Yes Yes Yes 21
  22. 22. Elegant Code public static void changeCurrency(float amount, public static void changeCurrency(float amount, Denomination[] denom) { Denomination[] denom) { 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
  23. 23. 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

×