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

ECE 458: Engineering Software for Maintainability

Sections 01 and 02, Spring 2021

(Also listed as ECE 496 section 05 for students not seeking design course credit)


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

Evolution 4
----
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: Online, TuTh, 1:45PM to 3:00PM
ECE458-02: Online, TuTh, 3:30PM to 4:45PM
Zoom link: See Piazza or Sakai

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: Anshu Dwibhashi (anshuman.dwibhashi AT duke.edu) and Lucas Liu (lucas.liu AT duke.edu)
TA Office Hours: By appointment

Links

Schedule

Thu 1/21. Introduction

Tue 1/26. 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...

Thu 1/28. 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?

Tue 2/2. Workday

  • Stand-up status meeting (quick!)

Thu 2/4. 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?

Tue 2/9. Effective professional presentations and technical demos

  • Guest panelist: David Klem, 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?

Thu 2/11. Workday

  • Stand-up status meeting (quick!)

Tue 2/16. 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

Thu 2/18. 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.

Tue 2/23. Testing, Debugging, and Software Quality

  • Guest panelist: Mekka Williams, Principal Engineer - Hybrid Cloud Engineering, NetApp
  • 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?
  • Due today by 8am:
    • Project report for evolution 1

Thu 2/25. Workday

  • Stand-up status meeting (quick!)

Tue 3/2. 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?

Thu 3/4. Workday

  • Stand-up status meeting (quick!)

Tue 3/9. Mini-spring Break (no class)

Thu 3/11. 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

Tue 3/16. Evolution 2 Reflection

Danger! Start Evolution 3 now! Due to the mini-spring break and the compressed semseter, the time available for evolution 3 is shortest of them all!
  • 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.

Thu 3/18. Workday

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

Tue 3/23. 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?

Thu 3/25. Workday

  • Stand-up status meeting (quick!)

Tue 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

Thu 4/1. 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.

Tue 4/6. Technical writing, software documentation, and intellectual property

  • Guest panelist: Dr. David L Kaminsky, Technology Specialist, Fish and Richardson.
  • The Bill of “Writes” by Beryl Pittman
  • Intellectual Property Primer from copyrightlaws.com
  • Developers Need to Start Paying Attention to Licenses by Brian Rinaldi
  • Are Software Patents Evil? by Paul Graham
  • Why software patents are evil by Simon Phipps
  • 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?
  • Intellectual property: Code is protected by copyright mediated by licenses, potentially subject to patents, and may contain trademarks and trade secrets. What's up with all that?
    • What license is your code under? What license are you subject to via all your dependencies? What about their dependencies, recursively? Are you compliant?
    • How can licenses protect us? How can they cause problems?
    • When should you pursue getting a software patent?
  • Due today by 8am:
    • Project report for evolution 3

Thu 4/8. Workday

  • Technology highlight presentation: Alex Qiao, the node-postgres library and tradeoffs of ORMs
  • Stand-up status meeting (quick!)
  • NOTE: Assign subsections of reading for next session's discussion (see here).

Tue 4/13. Teamwork and business stuff: leadership, communication, budgeting, and politics

  • Guest panelist: Craig Chadwell, Vice President for Products, SoftIron.
  • Guest panelist: Henry Vail, Vice President for Technology & Strategy, OneIQ.
  • 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?

Thu 4/15. Workday

  • Technology highlight presentation: Januario Carreiro, Django REST framework
  • Stand-up status meeting (quick!)

Tue 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

Thu 4/22. Overall Reflection

  • Final reflection case study presentations:
    • Section 1: Natasha von Seelen
    • Section 2: Ahmed Abualsaud, Maxwell Schettewi
  • 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?

Tue 4/27. *OPTIONAL* Party via Zoom at 2:30pm

  • *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 and chat. I'll reveal the project planning process.

Course overview and policies

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: Note: This course and its procedures are based on work by Drew Hilton, and some of the above is adapted from his syllabus.

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.

Production server freeze

(Added 2/23/2021) Starting on the first evolution deadline, you must abide the production server freeze rules:
  1. The production server is frozen from the moment of an evolution's deadline until 7 days before the next evolution's deadline. This is true even after your eval session and after an evolution's grades are posted.
  2. Frozen means that there can be no code changes, configuration changes, or database content changes. Exceptions are made for the in-class demo and informal uses of the server in the presence of an instructor or TA (e.g., showing us a bug to ask about it)
  3. During the time that the server is frozen, the server must stay up, and may be accessed by the myself or the TAs at any time. We may revisit past tests or do ad hoc testing.
If you inadvertently violate the production server rules (e.g. accidentally updating it), just let us know so we can be aware.

Equitable labor rule

(Added 2/23/2021) This is a rule I hope to never have to apply. In the event of a gross imbalance of team member effort (defined as a member contributing at or less than 50% of their share as estimated by the instructor), the instructor reserves the right to multiply that student's score on group assignments by their estimated contribution. Further, the instructor may elect to distribute points lost in this manner among the other members of the group.

As an example, assume a group with students A, B, C, and D. If the instructor determines that student D clearly contributed no more than 50% of their fair share on an assignment on which the group got a 60, the instructor may elect to decrease student D's score to a 30 (60*50%), and may further elect to distribute the 30 points so-removed to the three other members, raising their scores to 70 (60+30/3).

For cases where a student's contribution is at or near 0%, this may be done without warning. For cases where there was some significant effort, this action will only be undertaken after significant discussions and a sustained failure to change trajectory over time.

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