COMP 529 - Software Architecture

Report Guidelines

Here are a few guidelines for the various reports (homeworks, milestones) that will be submitted during the course. Non-respect of these guidelines will results in penalties.

Format

The text body font size must be 11 pt and the margins must be at least 0.75 inch. Line spacing should be single for milestone reports. Commands that must be entered on the command line and source code must be in monospace font (e.g., Courier New), and user interface pointers must be in bold. For example, click on the menu File | New.

The paper size must be US-Letter (no A4).

The file format must be PDF.

Submission

Homeworks must be submitted by email one hour before Thursday’s class, i.e., at 12:05 PM. Do not forget to write an appropriate email subject.

Milestone reports must be submitted on WebCT on Friday at 11:30 AM. See the project page for the exact dates.

References

A list of references may be provided at the end of the report. Prefix each reference with a number. References must be mentioned in the text, as close to the relevant part as possible, for example:

A foobaz is better than a foobar [1].

It is recommended to mention the same reference multiple times if the reference is used in multiple sections of the report. References that are listed at the end of a report but not mentioned in the body of a report are ignored. If you use the same reference multiple times in the same paragraph, mention the reference only once, as early as possible in the paragraph.

Large references like complete website and books are inappropriate: please refer to specific webpages or chapters.

Writing Tip: never use a reference number like a noun. Avoid:

The benefits of AOP frameworks were discussed in [1].

Prefer (note the active voice):

Many studies have discussed the benefits of AOP frameworks [1,2,3].

Content

  • Always write complete sentences. Fragments are only acceptable in diagrams and tables.

  • Never list a series of words without explanations. For example, avoid:

    Good architecture: scalability, security, deployment.

  • The spell checker is your friend.

  • Avoid marketing buzzwords:

    This component is the state of the art in...

    Scala revolutionized the way we see scalability...

    AOP is the best paradigm...

  • Avoid empty sentences:

    Google OAuth implementation allows users to be authenticated securely. Users authenticate through OAuth to access a service.

    The last sentence was unnecessary.