Code Style and Conventions

Code Style and Conventions should appear in your SDD. The central aims in devising a coding style for your projects is predictability and readability:

• Predictability Can members of your group identify semantic features of the code at a glance. You should avoid bad variable names (a, f(), etc), instead use nouns for variables and verbs for functions (m_date, up_vector, computeLocalTime()). Use names to indicate member variables "m_date". If you are using set/get style for member variables, use those names "setTime(), getTime()"; make sure you have symmetry in your names too.
  
  
• Readability Can you read the code and tell what it does. The pinnacle of readable code is Literate Programming, which intertwines documentation and source. You can move toward this without a special programming environment by enforcing good names, liberal use of space, and frequent English comments to lead the eye through the code.
  

Since many of you are using a web interface, be sure to have conventions for your HTML and style sheets, even if they are automatically generated.

Standard Java conventions.

Details on Naming Conventions.

An example style guide for Mozilla code practice. Note, this style assumes "C" code. Here is a more java friendly style guide called "Turbine".

An example of a code style enforcer for visual studio.

System Design Document (SDD)

The system design document will be a very important component of your system. Yet more writing! This document is designed for internal use, for your team. It plays an important role in system documentation and maintenance. A successful SDD will capture the design philosophy and system at a high level, as well as detailed object level descriptions. This document should reflect your requirements document, i.e. reference reqs by number, and identify how the requirements were captured by the system. Brad Appleton has a nice template for SDDs. One might consider using Doxygen to generate at least some of the SDD directly from the code comments.

Requirements Recap

Karl Wiegers has a nice article about Writing Quality Requirements. This article covers strategies for validating your requirements. Please pay attention to the section Reviewing Requirements for Quality.

Because the quality of any product depends on the quality of the raw materials fed into it, poor requirements cannot lead to excellent software.

Startup Myths

Thanks to Peter for this one.
Top 10+1 Myths of Business Geeks, by Ron Garret covers a few of the common misconceptions about starting a tech business. A few items are bit contrived, but important points.

As Dwight Eisenhower said: plans are useless, but planning is indispensable.

Journal Entry: Plan and Process

Journal entry assignment three asks you to discuss your plan for getting code done and integrated into your system. Please discuss how you will approach the problem of fulfilling requirements and what process you will use. How will you keep on track and avoid procrastination? How will you motivate your teem to do the same. Please be specific about your strategy, and identify how you utilise or contradict the ideas from existing process frameworks (Agile or RUP for example).

... due Thurday Oct 5

Systems Engineering Lecture from JPL

Friday Sept. 29, 10:00am, ME 218
Brian Muirhead, chief engineer at JPL, will be giving a lecture, "Take Risk, Don't Fail: The Art and Science of Systems Engineering." Please plan to attend, extra credit will be given if you submit a short summary of the talk.

--This talk will provide a unique overview and insight into the process of systems engineering and qualities of the engineers who practice it. Examples of specific problems taken from recent NASA/Jet Propulsion Lab missions including the Mars Exploration Rover, Deep Impact and Mars Pathfinder will illustrate different approaches and skills needed to identify, assess, resolve, and validate solutions to complex, multi-disciplinary problems. This talk will emphasize the inherent "fuzziness" of systems engineering problems and the roles and characteristics of the teams who must solve them.

Alternatives to the "Waterfall process"

The waterfall process is the traditional view of software engineering, where the stages of development proceed sequentially. In recent years, a number of alternative methods have been formalized and studied. Of these IBM's "RUP" (Rational Unified Process) and Agile XP ( Extreme Programming) methods stand out. Both of these methods emphasize the importance of communication and iteration. In general, RUP is best suited to larger groups or sparse teams, i.e. best for groups that can't always work closely together. Agile methods emphasise tight group collaboration, this is especially true for extreme programing approaches. These alternative methods offer important strategies for accomplishing complex system developments with tight time constraints.

Here is a link to a more descriptive coverage of Agile Software Development.

Top Ad$ense earners

Google's Adsense provides a simple mechanism for generating advertisement based revenue from web pages. John Chow has the latest roundup of top Adsense earners. Notice that the top earner does it all by himself!

Assignment 3: Proposal Revision & Presentation

The next assignment involves revising and polishing your proposal. It will be due Tues 12 Sep. On this date you should also have a short, 7 minute presentation describing the project. This will be done in front of the class, and each presentation will be critiqued. There are some common issues with all of the proposals, be sure to address these in your revision:

• Always have someone else read your proposal! Ask someone to give you feedback and explain your project to you. This will help you identify holes or unclear explanations.
  
• Avoid informal language, like "you" and "I". These can be directly substituted with "one" and "we". Imagine that the document speaks for you and your "company", rather than it being written by you.
  
• Background, background, background. Be sure to do your due diligence in finding competing work. It will be rare that you have truly novel idea, who else thought of it?
  
• Make strong points. Avoid weak or self deprecating comments. This document should convince me that you are the right person/team for the job.
  
• Avoid too much internal detail in system description. Your description should be detailed, but only with respect to system boundaries. Delving into specifics about its implementation will confuse the reader, and in many cases make the system seem fuzzier rather than more concrete. Focus on aspects of the description from an "outside" point of view.
  

Also, make sure that you have reasonable section headings, your cover sheet is only one page and contains your contact info, if you have an itemized budget be sure that it has a total at the bottom. You should go back through the assignment 1 description, and make sure you have addressed each of the topics. Your grade on this project will depend on the amount of improvement when compared to the draft you just submitted.

A Requirements Specification Template

The Volere Requirements Specification Template, available here , is a detailed breakdown of the requirements elicitation process. This document covers all of the categories you should consider when developing and negotiating the requirements for your project. While not all of the 26 categories will be immediately relevant to your work, this template can serve as a guide for evolving requirements during the lifetime of the software. Use this document in conjunction with chapters 4 and 12 in the book for the next phase of the project; negotiating requirements and deliverables.