Mon Feb 4 19:43:52 EST 2019
Some contents and dates may shift a bit.
The intent is that this will not be just hacking, but a serious attempt to simulate some aspects of reality: choosing something suitable to work on, planning how to get it together, designing it before building it (though allowing for the inevitable changes of direction as things evolve), building it in stages, testing it thoroughly, trying it out on real users, and documenting and presenting the result, all as part of a small team. If you do it well, this should be something that you can show with pride to friends and prospective employers; other Princeton students may use it extensively; you might even make money with it.
The project will involve many of the issues of software engineering as they occur in small, multi-person real-world projects. Some of this material will be discussed in class, and some will be found in assigned readings.
The considerations affecting the form of the project are:
The project this year will be the same as in previous years:
This is a very open-ended specification, so the big problem is likely to be defining a topic of the right size. Almost every web service will suggest something, perhaps novel or perhaps "We can do that much better"; either would likely be fine. Hiding, selecting, or merging data from existing web services is a possibility; shopping, news and other bots are examples, as are the myriad mashups that combine information from multiple sources. Mobile phone applications are often like this too, as are browser extensions.
Numerous web services (including Google, Amazon and Facebook) provide program interfaces, which might be a way to put a different face on some aspect of their systems. Using these APIs could be good for potential projects, and creating a good API is a fine example of a non-graphical user interface.
Look around campus for other possibilities: maps, tours, notification services, databases, and so on are all potentially interesting and feasible, though make sure that the information that you want to use is available -- concerns for privacy, property and turf can all get in the way of a great idea. We often hear about potential projects from staff, faculty and other students. If you want to explore further, come talk to us.
Some of the best projects come from noticing a task that is done by hand or poorly by computer, when it could be done really well by a suitable program, or where something complicated could profit from a neat user interface. Think about how rapid interaction might be used in some new application, or how some standalone program could be web-ified, or how some service could work on a phone. Or maybe focus on tools that make it easier to build such things, and create a couple of examples that demonstrate the wonders of your tools.
In our experience, in successful projects the people are really turned on by what they are doing, whether because it's their own idea and that's sufficient motivation, or because they are building something that someone else cares a lot about too. Either way, that kind of engagement usually leads to the best results. Be wary of projects where none of the group is really interested, or where one member is driving the whole thing, or where the application is too far away from your own experience.
Previous projects have included web-based calendars and financial systems; numerous improvements of campus services and agencies; rental and exchange systems; course evaluation, selection and scheduling; information services for the local environment; social networks; and a variety of map mashups.
The assignment is to create such a system, using any combination of existing tools and new code. The functionality that you should provide includes the following:
How big? There's no official requirement, but it ought to ultimately involve several thousand lines of code of your own; churning out a thousand lines of repetitive JavaScript or mechanically generating a bunch of Python with Django isn't enough. Some systems have been as big as 10,000 lines of C++; that's more than necessary, though it was great work. In any case, we will expect to see clean, well-written code, with appropriate attention to principles of sound software engineering.
Distributed or local? Most systems are distributed: the user interface runs on a client machine and the data is stored on a server. The processing might be at either end, or some of each. We strongly encourage systems that involve a network connection, even if it is only to a local host or the database, so as to leave open the option of distributed operation.
Languages, tools and environment? You can use any combination that appeals for any aspect -- web-based or stand-alone; Windows or Unix or Mac or phone; Java or Python or Javascript or C#; Ruby on Rails or Django or Flask; your own machine or a real server like Heroku or AWS. The only restriction is that your running system must be readily accessible so you can demo it effectively and we can run it for grading. We also require that you use a source code management system like Git; it will save your life sometime for sure, and it makes it easier for us to monitor your progress.
Make versus buy? Much modern software development is done by combining code and components that others have created. You can use as much of this as you like, as long as the finished product acknowledges the work of others, and has a substantial contribution of your own.
We have attempted to make this as open-ended as possible. This is your chance to invent something new, or to do something better than others do. You might think of this as practice for a new e-business or e-service, the sort of e-thing that made some of your predecessors here (like Meg Whitman and Jeff Bezos) into e-zillionaires. Of course if you have a really good idea and are acquired or do an IPO by Dean's Date, it's an automatic A+.
But you only have 12 or 13 weeks, so you can't get too carried away. Part of the assignment is to plan exactly what you are going to create, what each team member will be responsible for, and what interfaces you will require between components so independently-created pieces will fit together. What schedule will you follow? How can you work on different parts in parallel and keep them integrated? How will you ensure, if your time estimates are too optimistic (as they inevitably will be), that you have a working subset, rather than a non-working collection of partially completed pieces? How will you convince skeptical TAs and instructors that you are making progress, not just writing code (or doing nothing at all)?
Since the project will involve multiple people, a major task is to divide the work into suitable pieces, with planned interfaces. Each of these components should be a separate entity that can be implemented and tested separately. But you will have to think carefully about the interfaces between them: the problems caused by poor interfaces are a recurring theme in comments from previous projects (and, happily, so are the strongly positive experiences reported by groups that did a good job on interfaces).
The project will represent 60-65 percent of your course grade. All team members will get the same grade (with the potential for a correction in the unlikely event of someone not carrying their fair share of the load), so be sure that you all agree on who will do what, by when, and to what standard. Each person must contribute their fair share, including writing a reasonable fraction of the code for the system, no matter what other roles they play.
Here are some things you should start thinking about now; this list will be augmented over the next few weeks, and we will talk about it in class as well.
==================================================================
The following schedule is subject to change in details but the spirit is right. Take note.
Since the project involves most of the semester, it is possible to develop a significant piece of software, but serious planning and steady work will be required for your project to be completed on time. To encourage planning, organization and regular activity, the project has several important deadlines. [Some of the dates near the end may shift a bit; there will be adequate warning.] The TAs will be responsible for primary supervision of teams and I will act as backup and second-level ("bungee") management. You will be required to meet with your TA manager/mentor each week after spring break. These meetings are a graded component of the course, so preparation and attendance are mandatory -- no excuses.
We will also try to follow good software engineering practice as much as possible. We will lean heavily on things that have been helpful in previous offerings, such as design documents, status reports and reviews aimed at helping you to organize and us to monitor. All of these are also mandatory and graded.
Su Mo Tu We Th Fr Sa Feb 1 2 start thinking about possible projects and teammates 3 4 5 6 7 8 9 first class 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 Mar 1 2 team meetings with bwk completed by 3/1 3 4 5 6 7 8 9 10 11 12 13 14 15 16 design document due 17 18 19 20 21 22 23 spring break -- don't waste it 24 25 26 27 28 29 30 weekly TA meetings start this week 31 Apr 1 2 3 4 5 6 7 8 9 10 11 12 13 project prototype 14 15 16 17 18 19 20 21 22 23 24 25 26 27 alpha test 28 29 30 May 1 2 3 4 last class; beta test 5 6 7 8 9 10 11 demo days this week, probably Wed/Thu 12 13 14 15 16 17 18 projects due Sunday 19 20 21 22 23 24 25 26 27 28 29 30 31
Section 1 ("Overview") should provide a general overview of what your project is, what it hopes to accomplish and the like. Section 2 ("Requirements and Target Audiences") should provide a few sentences describing the problem that your system will solve. More specifically, you should describe in detail the intended users of your system, how your system will benefit them, and contrast with existing solutions. Section 3 ("Functionality") should give some typical use case scenarios. If you work through some scenarios carefully, the rest of the system will be a lot easier -- this should be done before you worry about implementation details. Joel Spolsky's articles on specifications are worth reading for a general guide.
Section 4 ("Design") should describe your major components. Each piece should have outlined what it does, how it connects and interacts with the other pieces, and their most likely implementation(s). At the very least you must cover your three "tiers". The business logic and/or middleware is likely "where the magic happens" with your specific project, so you will want to spell it out carefully. In this section you should pay specific attention to interfaces between components -- interfaces insulate each part of the system from details of the other parts, allowing modularity of both design and implementation. With proper interface design, you should be able to make significant changes to the details of your interface or database without changing the core code much, if at all.
Section 5 ("Timeline") should list significant milestones that you plan to achieve every week or so. Milestones should be a concrete task or feature that is 100% done, not a vague description like "coding" or "debugging". Allow for slippage, and for all the required "overhead": demo, documentation, etc. Consider what components constitute your minimal plumbing, your prototype, your alpha and beta versions, and how you can arrange your sequence of stages so you can stop at any time and declare success.
Section 6 ("Risks and Outcomes") is the place to show that you've thought about what you need to do and what might go wrong or cause delay. We're not interested in generic risks like someone getting sick, but in perils specific to your plan: learning new languages, tools, and systems; dependence on data or software or hardware acquisition. What will you do if your preferred path is blocked? Give this some thought, so you don't discover a month from now that you simply can't have something that you need
Once you have submitted your design document, a link to it should be included. Additionally, a list of the milestones timeline from that document should be included in HTML form on your website, along with adjustments to the timeline as the project progresses and the goals shift.
Once your team has developed its "elevator speech", that should also be included on the website.
Your project's elevator speech should be a single paragraph that states clearly and succinctly what your system does. What would you say if you were alone in an elevator with Bill Gates for 60 seconds, and wanted him to fund your project? The speech should be a short attention-grabbing description without big words but with good buzzwords. You may be asked to give your elevator speech during lecture; be prepared.
After your demo, your slides should be linked from the website. After submission, your final document should also be linked from the website.
Before each meeting with your TA, you should strive to resolve any technical issues, so that you can show concrete progress since the last meeting, ideally a perpetually working system with a monotonically increasing set of features. The meeting with the TA is a good time to discuss open issues regarding design choices, project evolution, and team responsibilities.
During meetings you should describe your progress since the previous meeting, as documented in your project timeline on your website, and as demonstrable with a working version. Given the short time scale, there really has to be progress every week. The TA's will be looking for evidence that you're getting somewhere, though of course there will be setbacks and dead ends; we just want to make sure those are under control.
Our intention is that the meetings will encourage you to think about what you have done and what you're going to do next. The meetings are a chance to talk things through, and get advice and opinion from someone supportive who is looking over your shoulder. The TA's job is not to solve your technical problems, and it's certainly not to tell you what to do -- it's your project. But pay attention, especially if your TA is concerned about something.
Everyone must come to all meetings if at all possible. If you absolutely must be away, courtesy and a concern for your grade mandates sending an explanation well before the meeting. Unannounced absences, and especially total no-shows, are unacceptable.
Be prepared. You might find it a good idea to meet among yourselves the day before your TA meeting. The time you spend thinking about and organizing for your meeting will pay off. The TA's are looking for you to be obviously prepared, with an organized agenda, and volunteering information; they should not have to drag things out of you, and they will definitely be unhappy if you're clearly just winging it with no evidence of effort ahead of time.
This is the time to start getting real users to test the system.
Drafts of written material (as described in other deliverables) should be underway.
The demo will determine a significant portion of your grade, so you (and the course staff) want them to go as smoothly as possible. In order to assure this, start thinking about your presentation now. You could picture your presentation/demonstration as an event that will make or break your "company" -- you'll be on the spot in a foreign place, with an audience, though the audience is really just a group of very supportive potential customers, investors, friends and family. As to content, the "trade show" metaphor is useful, but you should aim for more than just a glitzy demonstration -- you should also spend at least some time discussing the architecture, the trajectory of the project, and providing evidence that you learned something.
One possible outline of your presentation would be: a short introduction of of what your system is supposed to do; a demo of a small number of stable important features; a summary of other important features; a brief overview of architecture and implementation; an anecdote of something that worked well or failed disastrously such that you were able to take something away from the experience; and something that you might explore further or do differently if you were to start all over again or had more time.
You will be allotted 20 minutes, which is not a lot of time. Plan on using about 15 minutes, to leave time for questions, setup and teardown, and other delays. In previous years groups have done well on timing; rehearse to keep the streak alive. Plan demos that do not require much typing or mousing or window-switching -- this invites things to go awry, and invites the audience to get restless while you poke around. You just don't have enough time.
Have fun. These projects are really interesting, and the enthusiasm of their presenters helps make that evident to all in attendance. Because a healthy audience amplifies that enthusiasm, each student is required to attend three other presentations and you are strongly encouraged to attend more, for edification and moral support. Visitors are welcome, so bring your friends and family. Typical projects are great; come and hear about them. We will advertise the schedule of demos in advance.
The Product Guide should provide an overview of the system aimed at two targets: its typical end users, and its hypothetical continued developers and maintainers. The "user guide" portion should describe what the system does and how to get it to do what it does -- relatively simple installation instructions, and the features content typical of a non-technical user's manual. The "developer guide" portion should describe the internal structure of your system in intermediate depth, as though for a professional engineer taking over your project. Help them to understand how the system is put together, in an orderly and compact description, without getting mired in lowest-level details. The document should provide a good working description of the system and its implementation, but not a line-by-line walkthrough of the code. This also is the place where you implicitly acknowledge the software systems that you used but did not create.
The Final Report should describe how the project worked out. How good was your original planning? How did your milestones go? What was your experience with design, interfaces, languages, systems, testing, etc.? What surprises, pleasant or otherwise, did you encounter on the way? What choices did you make that worked out well or badly? What would you like to do if there were more time? How would you do things differently next time?
Imagine that you are writing this document for your (friendly!) boss or professor and want to explain what you learned that could be applied to the next project. Some groups present a single unified report, synthesized from the thoughts of all group members. Other groups prefer to write separate pieces of the report, since they focused on different project components and learned different things. Either is fine, but in both cases aim for true introspection: try to avoid repetition or banal generalities like "this was really interesting. we learned a lot".
This part is subject to revision; we might instead require access to your Github repository.
For the submission, collect all code and code-related files that you created for your project in one place, and compress them into a single file.
Specifically: Create a directory for named src. Copy
all source code to that directory. That includes anything you created,
especially source code and similar material. If you have help files,
images, data, etc., put them in the src directory too.
Sub-directories are fine. Do not include other files that are created
by compilation or downloaded from somewhere else: no object files,
executables, class files, etc., and no .git repositories. We don't want
to exceed some CS quota.
Compress the src directory to create a gzipped tar file
named with your group leader's netid netid.tar.gz. This is
an appropriate command sequence for joestu's group:
cd directory_above_src tar -cf joestu.tar src gzip joestu.tar
Be sure that your code is complete before you copy it to the src directory. We will be looking through your source code to get an idea of what you did and how well you did it, so everything should be there. Once you have created the tarball, submit it via Dropbox.
You will have 3 points per person in the group, excluding yourself, to distribute across the other members of the group. (That is, for a group of 5, you will have 12 points to split among 4 people; for a group of 3 you will have 6 points to split among 2 people.) The minimal score for any person is 0.
You will submit the feedback on Dropbox in a text file named peer.txt. The format of the feedback will be a list of netids and points allocated, followed by a single blank lines and then (optional) free-form text to describe your rankings. Please be concise and attempt to avoid turning the text description into a ranting opportunity. And please follow the specified format; it's not fun to edit 80 files by hand.
Here is an example of the list and text feedback for teammates Joe Student and Josephine Élève in a group of three:
jeleve 4
joestu 2
Joe contributed to the initial design of the project, but dropped off the face of the earth in April. He did get back with the program for the documentation, which I think is good, but I feel like Josephine and I really carried the project through to the demo. Josephine was a dream to work with because she was a good leader and always got her code done on time and in working order, but once Joe showed back up, she did sort of dump us with the documentation at the end.
The ratings of all other members will be taken into account when assigning individual credit for the project. Failure to participate in the peer rating process will automatically result in a rating of 0, regardless of the ratings of your teammates.
Grading for the project will be based on a number of criteria, including
There will be more information as we go along, to flesh out or clarify some of the sketchy parts here. There will also be class lectures on some of the pieces, like networking basics, user interface programming, web frameworks, and database software. You are encouraged to ask questions that will help clarify things for everyone. Murphy's Law applies to projects and their administration, so there will undoubtedly be screwups. We apologize for those in advance, but of course they too will be a simulation of reality...