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.
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. ‘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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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
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. 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