This is an archive of a course I taught Spring 2020, preserved here as a resource for future students.

ECE 458: Engineering Software for Maintainability

Sections 01 and 02, Spring 2020


Fig. 1: If your IDE looks like this,
you're doing it wrong.

PARTY
----
DaysHrsMinsSecs
Course survival checklist
  • Prepared with notes for next discussion?
  • On target for evolution deliverables?
  • Next evolution presentation/report ready?
  • Next out-of-class eval scheduled?
Quick links: Sched [ Jan Feb Mar Apr ] · Policies · Report rubric · Preso rubric · Extra readings

Overview

ECE458-01: Hudson 139, MW, 1:25PM to 2:40PM
ECE458-02: Hudson 139, MW, 3:05PM to 4:20PM

Instructor: Dr. Tyler Bletsch
Email: Tyler.Bletsch AT duke.edu
Office Hours: By appointment (but totally fine - feel free to request a meeting)

Teaching Assistants: Brandon Guo (brandon.guo AT duke.edu) and Walker Willetts (walker.willetts AT duke.edu)
TA Office Hours: By appointment

COVID-19 plan

Taking into consideration the COVID-19 announcement, the calendar for the remainder of the course has been rewritten. Evolution 3 has been extended 5 days.

Here's how class sessions will work:

  1. For workdays, we will do the following:
    • Before the start of classes, each team will elect a Zoom Master who will provide a link to their personal room to myself and their teammates. See Piazza for the Zoom Master spreadsheet link.
    • Everyone will start by joining the full-class Zoom meeting that will be sent via calendar invite. Here we have our standup meeting and discuss any issues relevant to the full class.
    • Everyone will drop this joint meeting and join their group's Zoom Master's room. Here, groups can collaborate freely until I pop in and have the usual status Q&A.
    • I'll post on Piazza with any issues that were raised with individual groups that are relevant to everyone.
  2. For discussions and reflections, everyone will join a class-wide Zoom meeting via calendar invite. If possible, we'll just stay unmuted, but if it's too chaotic, we'll do some kind of virtual hand-raising thing. I'm working on getting our guest discussion panelists onboard with this, so we'll hopefully still have outside voices in the conversation. Discussion notes will be submitted via Sakai.
  3. For presentations, everyone will join a class-wide Zoom meeting via calendar invite where everyone is on mute by default. I'll pass presenter role to speakers to present via screen share.
  4. For evaluations, the group will join a Zoom meeting via calendar invite with myself and a TA and we'll do the usual thing.

Let me know if you have questions or concerns. If you have unique challenges because of this extraordinary situation, please don't hesitate to reach out. We'll all get through this together.

Links

Schedule

Wed 1/08. Introduction

Mon 1/13. Programming Languages and Frameworks

  • Beating the Averages by Paul Graham (the Blub Paradox)
  • Your group's first design decision will be which language and framework to implement your project in.
  • Part 1: Language bootcamp: To help, a number of students are asked to research a language/framework and deliver:
    1. a 4-minute intro presentation, and
    2. a written one-page quick-start containing links and information for any team that might wish to deploy it.
    To ensure good diversity, I'd like to at least see solutions based around:
    • NodeJS (Meteor, MeanIO, Sail, Koa, Express, etc.),
    • Python (Django, Flask, Pyramid, etc.),
    • Ruby (Rails), and
    • a Microsoft language (e.g. C#/ASP.NET).
    Additional options are encouraged, including esoteric ones like Go, Rust, Scala, OCaml, Squeak, Scheme, etc. You can do Java if you really want. This part is strictly technically focused; discussion of the merits of the languages will take place in part 2.

    Student notes/materials:
  • Part 2: Tradeoff discussion: After the brief technical intros, our first class discussion will focus on topics to consider in making your language selection. Here are some concrete discussion points to consider:
    • What is the "Blub paradox"? Do you suffer from it?
    • What language features make a programming language "Good"? Why?
    • How do the relative importance of those features change in different situations?
    • Consider a handful of programming languages which you know or which were covered—how well (or poorly) do these languages provide the features you described above?
  • NOTE: Teams will be presenting their project management plan in two days...

Wed 1/15. Project management

  • Evidence-Based Scheduling by Joel Spolsky
  • In my experience, bad planning and logistics is just as likely to sink your project as design issues. Let's fix that.
  • Each team must identify and report on a tool and/or technique to address each of the following issues:
    • Project dependencies, timeline, and opportunities for parallel effort (e.g. Gantt chart?)
    • Bug/task tracking and assignment
    • Source code control and governance (branching, merging, code review, deployment, etc.)
    You don't necessarily need a heavyweight tool for each thing; just be able to describe how you'll address them.
  • Let's discuss some of the planning issues you may encounter.
    • What are ALL the steps that will go into a release (evolution) of your softare?
    • Is it worth anything to know you're behind schedule? What can you do with that information?
    • How could a project's execution be "inefficient"? How can this inefficiency be detected and corrected?
    • The above practices are mostly about improving efficiency, but how might they also improve the quality of the final product?

Mon 1/20. Martin Luther King, Jr. Day (no class)

Wed 1/22. Workday

  • Stand-up status meeting (quick!)

Mon 1/27. Good Design: What is it?

  • Guest panelist: Daniel Holmes, Senior Software Engineer – Development Tools and Services, NetApp
  • Basics of the Unix Philosophy from The Art of Unix Programming by Eric S. Raymond
  • Sections 5.1 and 5.2 of Chapter 5 of Code Complete by Steve McConnell
  • An Incremental Architecture Approach to Building Systems by Jan Stenberg
  • The primary goal of this course is to get you thinking about how to design software better. Accordingly, our second class discussion will focus on what we consider to be "Good" design. Here are some concrete discussion points to consider:
    • What are the hallmarks of a Good design?
    • What are the hallmarks of a Bad design?
    • How do these considerations tie into the language features you found desirable?
    • How do you plan to ensure good design?
    • How can you evaluate the Goodness of your design...
      • ...in the planning stages?
      • ...in the implementation stages?
      • ...when maintaining it?
    • If you made bad design decisions, how do you decide between sticking with it and redoing it?
  • What is essential complexity? Accidental complexity?
    • How do we deal with the essential complexity?
    • What might lead us to create accidental complexity?
    • Consider the following quote from Neal Ford: "It's the duty of the architect to solve the problems inherent in essential complexity without introducing accidental complexity." How can we do this?
  • When we design programs, we actually have two very different tasks: Programming in the Large (PitL) and Programming in the Small (PitS). In the former, we consider large scale design considerations: modules, their interfaces, etc. In the latter, we consider design considerations on a much smaller scale: implementation of a module, class, or function.
    • Which of your good design/bad design features contribute to PitL, and which to PitS?
    • Which of the important language features that you identified earlier are important for PitL vs PitS?
    • How do the two tasks relate? Are they mutually exclusive? Serially dependent? Iterative refinements of each other?
    • Which is more important: PitL or PitS? Put a different way, if you had to work on a piece of software which did one excellently and one badly, would you prefer good PitL design coupled with poor PitS design or poor PitL and good PitS?
    • Which scale of design aspects is easier to modify when requirements change? How does the answer to this question inform our design decisions?

Wed 1/29. Effective professional presentations and technical demos

  • Guest panelist: David Klem, Strategic Solutions Architect, Dropbox.
  • The Listener's Bill of Rights by Beryl Pittman
  • How to pull off a slick tech demo (in 5 easy steps) by Martin Kleppmann
  • You're going to present your first evolution soon. Some questions to ponder:
    • You've certainly born witness to bad presentations...what made them bad?
    • What defines "professionalism" in a presentation?
    • What are some techniques and tricks to help give a smooth presentation?
    • In what ways might a speaker lose credibility?
    • If you show up to do a presentation and you can't connect to the projector, do you look like a giant fool? (HINT: yes.) What can be done to prevent this?
    • Public demos tend to fail with almost magical regularity. What can you do to mitigate this risk?

Mon 2/03. Workday

  • Stand-up status meeting (quick!)

Wed 2/05. Evolution 1

  • Oral presentations
  • Due today by 8am:
    • Code for this evolution should be submitted
    • This same code should be kept deployed on a production machine
    • Your eval meeting should be scheduled

Mon 2/10. Evolution 1 Reflection

  • Each team should come prepared to discuss:
    • What parts of your design do you think will set you up well for the future? Why?
    • What parts of your system are you most worried about going forward? Why?
    • How is your project/software management methodology working? Have you had to evolve it?
  • After hearing everyone present, we will discuss tradeoffs between different teams' approaches.

Wed 2/12. Workday

  • Stand-up status meeting (quick!)
  • Due today by 8am:
    • Project report for evolution 1

Mon 2/17. Testing, Debugging, and Software Quality

  • Software Testing by Sarah Heckman — a primer on the fundamentals
  • The case of the disabled logins — an interesting diagnosis of a malfunctioning Linux-based kiosk
  • Testing: Systematic testing is an important part of the software creation process. In a healthy development environment, testing is generally automated and regular, including nightly regression testing and a robust, end-to-end QA effort conducted before release. Today, we talk about how it fits into the design process.
    • Where do tests come from? How does testing differ from debugging?
    • How do you automate testing? When should automatic testing occur?
    • How can your design decisions simplify (or complicate) testing?
    • How do you design for testability?
    • How does your testing infrastructure/plan have to change in the face of changing requirements?
    • Can you design your testing infrastructure/plans to be more resilient to evolution?
  • Debugging: Most programmers spend more time debugging code than writing it. How can our design improve our debugging process?
    • When in the programming process is our code must vulnerable to introduction of bugs?
    • How can our design decisions reduce (or increase) the prevalence of bugs?
    • How can our design decisions simplify (or complicate) debugging?
    • What constitutes "good" debugging practices?

Wed 2/19. Workday

  • Stand-up status meeting (quick!)

Mon 2/24. User interface design

  • User Interface Design Basics from usability.gov
  • (Just skim) User Interface Elements from usability.gov
  • Effective Visual Communication for Graphical User Interfaces by Suzanne Martin (from 1995).
  • 7 Rules for Creating Gorgeous UI (Part 1 only) by Erik D. Kennedy.
  • What is the motivation for studying user interface design?
  • Have you ever seen a "bad" UI? What made it bad? What are the risks of bad UI design?
  • How should your software architecture inform your UI design? How might it inadvertantly influence UI design?
  • What design changes have you made to your UI during or since evolution 1? Why?
  • How can a UI support both novice and advanced users simultaneously?
  • Given the subjective nature of aesthetics, how can we have "rules" in UI design? What rules might change over time, and which might be timeless?
  • What is accessibility? How accessible is your software right now?

Wed 2/26. Evolution 2

  • Oral presentations
  • Due today by 8am:
    • Code for this evolution should be submitted
    • This same code should be kept deployed on a production machine
    • Your eval meeting should be scheduled

Mon 3/02. Evolution 2 Reflection

Danger! Start Evolution 3 now! Don't tune out because spring break is coming! Account for spring break in your Evolution 3 schedule planning!
  • Each team should come prepared to discuss:
    • Looking back on what you considered your strengths...were they strengths?
    • Looking back on what you considered your weaknesses...were they weaknesses? What did you do about it?
    • What parts of your design do you think will set you up well for the future? Why?
    • What parts of your system are you most worried about going forward? Why?
    • How is your project/software management methodology working? Have you had to evolve it?
  • After hearing everyone present, we will discuss tradeoffs between different teams' approaches.

Wed 3/04. Workday

  • Due today by 8am:
    • Project report for evolution 2
  • Stand-up status meeting (quick!)

Mon 3/09. Spring Break (no class)

Wed 3/11. Spring Break (no class)

Mon 3/16. COVID-19 Break (no class) !

Wed 3/18. COVID-19 Break (no class) !

Mon 3/23. Workday

  • Stand-up status meeting (quick!)

Wed 3/25. Maintainability and Refactoring vs. Rewriting

  • Guest panelist: Rebecca Register, Kernel Software Engineer, NetApp.
  • Things You Should Never Do, Part I by Joel Spolsky
  • How To Survive a Ground-Up Rewrite Without Losing Your Sanity by Dan Milstein
  • You are almost done with the semester, and have just about finished three evolutions of the requirements. Hopefully you have significant thoughts on maintaining code in the face of changing requirements, the topic of today's discussion:
    • What kind of evolutions were most difficult to deal with?
    • Can you generalize what makes a specific type of requirement evolution easy or hard to deal with?
    • What makes code easy (or hard) to maintain?
    • How does this inform our design decisions?
    • What is different when you modify code someone else wrote? How do you mitigate these difficulties?
    • Did you ever consider a rewrite of all/part of your project? What are the pros/cons of a rewrite vs. a refactor?

Mon 3/30. Evolution 3

  • Oral presentations
  • Due today by 8am:
    • Code for this evolution should be submitted
    • This same code should be kept deployed on a production machine
    • Your eval meeting should be scheduled

Wed 4/01. Evolution 3 Reflection

  • Each team should come prepared to discuss:
    • Looking back on what you considered your strengths...were they strengths?
    • Looking back on what you considered your weaknesses...were they weaknesses? What did you do about it?
    • What parts of your design do you think will set you up well for the future? Why?
    • What parts of your system are you most worried about going forward? Why?
    • How is your project/software management methodology working? Have you had to evolve it?
  • After hearing everyone present, we will discuss tradeoffs between different teams' approaches.

Mon 4/06. Effective technical writing and software documentation

  • Guest panelist: Dr. David L Kaminsky, Senior Technical Staff Member, IBM.
  • The Bill of “Writes” by Beryl Pittman
  • Writing: Your next evolution is due soon, and soon after you will write your reflection report about it. In this discussion, we are going to talk about what makes good writing versus bad writing, and look for parallels with program design. Specific discussion points to consider include:
    • What are the hallmarks of a well written document?
    • How can you tell if what you have written is good or bad? If you identify something as being poorly written, how do you improve on it?
    • Compare and contrast good writing and good program design.
    • Compare and contrast the process of writing with the process of programming.
  • Documentation: most programmers hate writing it, but wish they had more of it to read...
    • How much documentation has your team written? What form does this take? Are you happy with it?
    • What makes good documentation?
    • Documentation takes time, but what are some ways in which it might save more time than it takes?
    • Can good code documentation improve the quality of the product from the user's perspective?
  • Due today by 8am:
    • Project report for evolution 3

Wed 4/08. Workday

  • Stand-up status meeting (quick!)

Mon 4/13. Workday

  • Stand-up status meeting (quick!)
  • NOTE: Assign subsections of reading for next session's discussion.

Wed 4/15. Teamwork and business stuff: leadership, communication, budgeting, and politics

  • Guest panelist: Craig Chadwell, Senior Product Manager, Lenovo
  • Guest panelist: Henry Vail, Technical Director for Software-Defined Infrastructure, Lenovo.
  • Chapter 1 of How to Win Friends and Influence People by Dale Carnegie
    (and in the interest of time, you'll be forgiven for just skimming some of the more lengthy anecdotes...)
  • Technical Debt by Steve McConnell
  • A assigned subsection from How to Win Friends and Influence People by Dale Carnegie
    (one or two of the set {3.1-3.12, 4.1-4.9}. — See here for subsection assignments)
  • Capex vs. Opex, Diffen.com
  • Let's discuss how teams affect software design and implementation:
    • What benefits does team programming have?
    • What difficulties does it introduce?
    • How does leadership/governance work on your team, i.e., how are decisions made and disagreements resolved?
    • How should you deal with a peer who seems discouraged or you feel may be having trouble contributing?
    • How would your approach differ with a peer who you feel could be working harder?
  • Whether you're headed to a big corporation, a small startup, or an academic role, it is certain that non-technical business issues will "intrude" on your work. In my experience, once you pass a certain level of technical expertise, your career will likely be defined by your understanding of leadership, communication, budgeting, and politics.
    • What makes a good leader? A poor leader?
    • How do you demonstrate leadership potential when you do not yet have a leadership role?
    • How might someone fail to convince others even when they're right?
    • What motivates decision makers in a business?
    • How could software design decisions affect the budgeting of a software project?

Mon 4/20. Evolution 4

  • Oral presentations
  • Due today by 8am:
    • Code for this evolution should be submitted
    • This same code should be kept deployed on a production machine
    • Your eval meeting should be scheduled

Wed 4/22. Overall Reflection

  • Each team should come prepared to discuss:
    • Looking back on what you considered your strengths...were they strengths?
    • Looking back on what you considered your weaknesses...were they weaknesses? What did you do about it?
    • How did your project/software management methodology work?
  • Revisit the previous discussion topics and contemplate how your answers to these questions have evolved.
    • What specific lessons about designing for evolving requirements have you gained from the class project and discussions this semester?
    • What were the most important of these lessons?
    • How can you apply the lessons you learned to design to guard against difficult requirement changes?

Mon 4/27. *OPTIONAL* Party via Zoom at 2:15pm

  • *NON-OPTIONAL* Due today by 8am:
    • Final project report
      (Sorry that this is due after LDOC...I had to find time somehow)
  • We'll hang out on Zoom, watch the marketing videos, and I'll reveal the project planning process.

Course overview and policies

Note: This course and its procedures are based on work by Drew Hilton, and some of the below is adapted from his syllabus.

In order to experience long-term software development and its effects on maintainability, you will be developing a semester-long software project. The requirements for this project will be released in four phases called evolutions. You will complete the project in groups of four students. Once you set your groups, you may not change them, so choose carefully!

The fundamental teaching mechanism at work in this course is reflection: by building a large and evolving software system, you will make decisions; some will turn out well while others may be costly, and that's okay. To get the most out of this course, be mindful of your actions and reflect on lessons learned over time.

Grading

Your grade will be broken down as follows:

Academic integrity

I take academic integrity extremely seriously. Academic misconduct will not be tolerated, and all suspected violations of the Duke Honor Code will be referred to the Office of Student Conduct (for undergraduates) or the departmental Director of Graduate Studies (for graduate students). A student found responsible for academic dishonesty faces formal disciplinary action, which may include suspension. A student twice suspended automatically faces a minimum 5-year separation from Duke University.

The expectations for this course are that anything you turn in (code, project report, etc.) will reflect the work of your group. I expect that you will not copy code/text from or share code/text with other groups, nor have people outside your group write any of this. You are welcome to (and encouraged to!) share design ideas during class discussions. If you choose to use ideas presented by other groups, you should give credit where credit is due: in your written analysis, when you discuss that element of your design, you should note who you got the idea from.

Other issues

Feeling overwhelmed or don't know where to start on something? Come talk to me.

Group dynamics issue?: Come talk to me.

Readings I like but couldn't fit into the schedule

Back to Dr. Bletsch's page