ece264/solutions/ECE264Solutions/PA01/README

********************************************
* DO NOT SEND EMAIL TO THE TEACHING STAFF. *
********************************************

If it is related to the course, please post it in Blackboard -
Discussion.  Use email for only private issues.  The teaching staff
will ignore email that is related to the course and not private.  You
will not receive any response.

=====================================================================

In this assignment, we will compute several properties of an array of
integers.

PLEASE NOTE: 
(1) You should only modify the file answer01.c 
(2) You can modify this file however you want, including adding additional
functions. (This is true for all assignments.)  
(3) You must only submit the file answer01.c for marking
(4) Parts of the assignment have been written for you, but these parts do 
not appear in the file answer01.c. Please browse through these files 
(pa01.c and pa01.h).

You should not add the main function to answer01.c.  Doing so will
guarantee that your will program fail and you will definitely receive
zero.  The main function is already provided in pa01.c.

If a file is marked as "do not modify this file", you should not
modify this file in any circumstance. Modifying this file will
guarantee that your program will fail and you will definitely receive
zero.  If you believe there are mistakes in the code given to you,
please post your questions, corrections, or suggestions in Blackboard
Discussion.

This assignment includes many pieces of useful information and you
will learn these pieces in the coming weeks.  Do not worry if you do
not understand everything in the first week.  Focus on writing the
functions in answer01.c.  If you have taken the prerequisite CS 159,
you should have no problem filling the code for these functions.

If you find this assignment unreasonably difficult, you do not have
the necessary background taking ECE 264.  It is advised that you take
CS 159 first.  If you cannot do this assignment easily, you are likely
to find ECE 264 unreachable.

If you need help, please visit the intructors' or the teaching
assistants' office hours. 

DO NOT SEND EMAIL.  Post your questions in Blackboard - Discussion.

================================ 
= Getting the Assignment Files =
================================

Assignments will be distributed to you via the version control system
"git". This very useful program will allow the teaching staff to make
modifications to assignments as problems arise, and then distribute
them to all of you. Version control will show exactly which lines have
been changed.  As students, you will have "read-only" access to the
assignment repository. The URL for the repository is:

https://github.com/yunghsianglu/ECE264Assignments.git

Use the "clone" command to get a copy of the files:

git clone https://github.com/yunghsianglu/ECE264Assignments.git

Once you have a copy of the files, you can "cd" into the repository
and use the "pull" command to get the latest version of the assignment
files:

cd ECE264Assignments 
git pull

Sometimes mistakes are found in the assignments. The instructor will
tell you to obtain a new version and you should type the command

git pull

====================== 
= Assignment Details = 
======================

In this assignment we shall: 
* add all elements in an array of integers 
* determine whether any element in the array is a negative number 
* determine whether the elements' values are always increasing

This program has the following files: 
(1) pa01.h      A header file 
(2) pa01.c      A C file that contains "main", the program entry point
(3) answer01.c  A C file (only edit and submit this file)
(4) Makefile    A file that "make" uses to build and test your solution

To use the makefile, you need to cd into the assignment directory and
type "make" in the Linux terminal. Type "make help" for a list of
options. For example:

ECE2644Assignments/PA01 > make help

After you finish this program, upload answer01.c to Blackboard and
submit it. Your program /must/, *must*, !!MUST!! compile against the 
original assignment files (pa01.c and pa01.h), otherwise you will get
zero. NO EXCEPTIONS.

You MUST test your program on native Linux (not cygwin, not
Virtualbox, not MinGW ...).  There were many cases when students
incorrect programs appeared working on cygwin or virtualbox.

========================= 
= Using Version Control =
=========================

For PA03, PA04, and PA05, you will need to show evidence that you are
using version control. You can use the version control tool of your
preferrence; however, we recommend that you learn git. The evidence
required is the log file of your commits.

Version control is not required for PA01; however, it is worth
figuring this out as soon as possible.  Version control is an
*essential* tool for computer programming in groups, and is also
highly recommended when working on single person projects as
well. Spend the time now to understand what you are doing, and that
will *save* you a lot of time later.

Conceptually there are two repositories to deal with: the repository
where you do your work (you control everything), and the repository
that the teaching staff use to distribute assignments to you. (URL
given above.) This second repository will hence-forth be called
"R-problem". The repository that you control will be referred to as
"R-answer". These *must* be in /separate/ directories in your account.

If you mix the two repositories, you run the risk of erasing your work
when the instrutor asks everyone in the class to do "git pull".

Do not modify anything in R-problem because it is read-only for
you. When you need to do a "git pull", git will want to delete all
your changes! IF YOU MODIFY R-problem, YOUR CODE WILL BE ERASED WHEN
YOU DO "git pull".

To set up R-answer, you will need to do some reading on the
Internet. There are many useful tutorials, and a bit of jargon that
you must master. The Internet contains everything you need to know.
Below is the URL for the official git tutorial. It is a starting point
for your learning of git:

http://git-scm.com/docs/gittutorial

Every non-trivial project is managed by version control.  

Once you have done "git pull" (or git clone for the very first time)
in R-problem, you will need to immediately copy the problems to
R-answer. Then, write your programs in R-answer, and remember to
commit and push often. It is advised that you COMMIT AND PUSH AT LEAST
ONCE A DAY. Since this is a one-person project, it is perfectly
acceptable if you commit and push every hour or every ten minutes.

In the rare cases when you are suspected of copying code, the commit
log can be used as definitive evidence that you are developing your
solutions step by step. However, if you commit only once before
submission, you will not be able to use your commit log as evidence
for your defence.

ECE 264 requires that you submit source-control logs for only three
assignments (PA03-PA05). After these three assignments, you are
expected to continue using version control by yourself, even though it
is no longer a requirement for grading.

You can use the version control system of your preference (git, svn,
cvs...)  as long as you can provide evidence that you are using
version control.

IF YOU DO NOT PROVIDE EVIDENCE OF USING VERSION CONTROL in PA03-PA05,
YOUR SUBSEQUENTIAL ASSIGNMENTS WILL NOT BE GRADED AND YOU WILL
DEFINITELY RECEIVE F IN THIS COURSE. THERE IS NO EXCEPTION.

=================================================================

How does computer grading work?

Your program will be graded in three ways:

* whether the outputs are correct
* whether the program has invalid memory accesses
* whether the program has any warning messages, use global or
  static variables ...

The first is determined by using the "diff" command.  The outputs of
your program is compared with the expected outputs.  Your program's
outputs are stored in the "outputs" directory.  The expected outputs
are stored in the "expected" directory.  You can use this command to
see whether they are different

    diff outputs/output0 expected/expected0

We use "diff -w"; "-w" ignores the difference caused by space.

The second is determined by the reports produced by valgrind.  In the
outputs directory, you can see files called "valgrind-log.."  At the
bottom of each file, there is a line called "ERROR SUMMARY".  Your
program should have no error.  If there is an error (or errors),
valgrind reports which line causes the error.

The third will be checked by another program (not given to you).
Since you can see the warning messages and you know whether you are
using global or static variables, it is unnecessary to give you the
checker.


=================================================================

In ECE 264, you should ALWAYS turn on gcc warning messages by adding

-Wall -Wshadow

after gcc.

These warning messages have helped many students discover problems in
their programs.  Thus, you should always use them. You will lose 1
point for each warning message (25% of each assignment). This will be
strictly enforced and there is absolutely no exception in any case.

=================================================================

You should not have space in a file name.  The ISO 9660 standard for
file names and directory names does not allow space. There are many
cases when space in file (or directory) names crashed systems.  If
your submission includes a file whose name contains space, it very
likely that you will receive zero in the assignment.

=================================================================

This assignment asks you to submit only one file.  Later assignments
will ask you to submit zip files that include mulitiple files.  It is
your responsibility submitting all needed files.  If you fail to
submit all needed files, and your program does not work, you will
receive zero.  The teaching staff will NEVER accept any late
submission for any reason. DO NOT ASK FOR AN EXCEPTION.

The teaching staff will NEVER go to your computer or your account for
grading.  Do not tell the teaching staff that "I have not changed the files
since the submission deadeline."  

Your assignment scores depend ONLY on what you submit.  

No late submission is accepted for any reason.  There is absolutely no
exception whatsoever.  The instructor will not respond to any request
for extension.

DO NOT ASK FOR AN EXTENSION.  

The instructor may give the whole class extensions.  The teaching
assistants are not authorized to give extensions.

=================================================================

It is irrelevant whether your program runs correctly on YOUR computer.
If your program is wrong (crashes, produces incorrect output, leak
memory, etc.) during grading, you will lose points.

The assignments will be graded on ECN-managed Linux computers.  You
should test your programs on these computers.  Some incorrect programs
may crash on Linux but they do not crash in MacOS os Windows (using
cygwin or virtualbox).  It is known that valgrind (memory error
detector) does not work on MacOS.

Please do not tell the teaching staff tHat "My program is perfect on
my machine." This statement is irrelevant in grading.

=================================================================

You should never use global variables or static variables.  You should
never use goto or assert in your programs.  The instructor will
explain the reasons.

You will receive zero if your program includes 

* one or more global variables
* one or more static variables
* one or more goto
* one or more assert

Global constants are acceptable; static functions are acceptable.

====================================================================

Some books encourage readers to use assert, something like this

     assert(x > 0);

This will stop the program if x is not positive.  These books claim
that by stopping your program, you will be able to debug.

These books are wrong.  

Why?

Why would you use assert?  You use assert because you are not so sure.
If you are 100% certain that x is positive, you would not use assert.
You would not waste time typing that line.  Would you write this?

    x = 1;
    assert(x > 0); /* assert immediately after x is assigned to 1 */

Probably not. Why not? You are certain that x is positive.

Thus, you use assert only if you have doubt.  Here comes the problem.
If you use assert and the condition is false, the program stops.

Imagine that you are writing a program for a large system.  Something
unexpected happens and you stop the program! There is no chance to
handle the problem.  This can easily cause a disaster.

As an example, a company writing flight control software found someone
wrote this

   assert(distance of two airplanes > safe distance)

In one of their tests, the company intentionally simulated the
situation when two airplanes were too close and a collison was
possible. This assert statement caused the flight control system to
crash.  It took several minutes to reboot and restart the system.  The
two planes collided in this simulation.

Why did the software develop use assert?  Because a book said so.

Many of you will have chance developing safety-critical systems.
Assertion failure could create significant damage, injury, or loss of
lives.

If you are responsible software developer, you need to detect and
HANDLE problems. DO NOT STOP THE PROGRAM.  This is an important
concept.  Stopping the program is irresponsible.

When C was designed, the concept of exception handling was not
invented yet.  Newer languages, such as C++, Java, and Python, have
exception handling.

Do not use assert.  It is an irresponsible way of writing programs.


====================================================================

You are encouraged to talk to the teaching staff if you have any
questions.  When you ask questions, please be as precise as possible
and provide as much information as possible.  Many students ask
questions by saying, "My program does not work. Can you help me?"
This sentence provides no information and additional information is
needed before anyone can help you.

The teaching staff will help you but you need to provide more
information.  When you ask questions, please provide the following
information:

* Which machine do you use?  
* What is the output of gcc?  
* Does the program generate any output on the screen or saved in a
  file?
* Does the program terminate abnormally (such as segmentation fault,
  bus error)?
* Does the problem appear consistently, every time you run the
  program?
* Have you initialized all variables?
* What does valgrind say about your program? 
* What is the call stack shown in gdb (or ddd)?
* Are the indexes for arrays valid? Remember that if an array has n
  elements, the valid indexes are 0 to n - 1; n is an INVALID index.

One goal of ECE 264 is to teach you to ask the right questions and
more important answer your own questions.  Before you ask any
question, please answer the questions above first.

Also, please remember that "My program produces correct outputs" does
**NOT** mean the program is correct.  It is possible that your program
has some hidden problems.  There are many cases that those hidden
problems are discovered in grading.  "My program produces correct
outputs" is **NOT** a reason to believe that your program is correct.
The common problem is that the program has invalid memory accesses or
reading uninitialized memory.

Consider an analogy.  You drive a car and run red lights.  You do not
hit anyone and reach your destination.  Does this mean running red
lights is acceptable? No.  If you run red lights often, someday you
will hit someone.  

Please remember that correct outputs does **NOT** mean your program is
correct.  

====================================================================

Computer programs follow logic flows.  Thus, understanding logic is
important. Consider the following code

   if (x == 0)
   {
      y = 1;
   }

If y is not 1, x cannot be zero.
However, if y is 1, x may and may not be zero.  Why?

   x = 1;
   y = 1;
   if (x == 0)
   {
      y = 1;
   }

Even though x is not zero, y still can be one.  Some students believe 
that x must be zero if y is one.  This is incorrect.

Another important concept is the difference between causality and
correlation.  If your program always have x is zero and y is one at
the same time, does this mean the program has this statement?

   if (x == 0)
   {
      y = 1;
   }

No.  It is possible that 
  
   if (z == 0)
   {
       x = 0;
       y = 1;
   }

In this case, x does not make y to be one.

====================================================================

Many students try to debug their programs by testing.  Testing can
only tell you something is wrong.  Testing will not tell you what is
wrong and how to fix it.

                      READ YOUR PROGRAMS

Sometimes students are surprised why the teaching staff can find and
fix problems so quickly.  The teaching staff read code carefully.  If
you want to write correct programs, read your code carefully after you
type in a few lines.

Do not copy-paste code.  You may find that some assignments ask your
programs to do something similar but slightly different.  Copy-paste
code seems a good and natural way to handle this situation.  However,
copy-paste code is the invitation of endless debugging.  You will very
likely forget to make necessary changes.  Even worse, if you find a
problem in one place, you will likely forget to fix the problem in
mulitiple places.

You should assume that you will make mistakes and try to develop a
strategy to discover and correct mistakes.  

Do not write a lot of code at once. Write a small section of code and
make sure it is correct, before you write more code.  If you take a
small step each time, you can finish the assignments much faster.

If you rush, you will spend more time.

====================================================================

All test cases are given to you and Makefile explains how your
programs are graded.  You are responsible making your programs work.
Do not expect any point if your program does not work.  You will NOT
get 90% points if you write 90% code.  If you write 90% code, it is
very likely that you will receive no point at all.

You will lose most points (possibly all) if your programs have invalid
memory accesses during grading.  It does not matter whether your
programs "work" when you test them.  If your programs have problems in
grading, you will lose most points.  Again, it is your responsibility.

The teaching staff grade programs based on the functionalities, not
sympathy; the teaching staff will not negotiate scores.  If you want
to receive high scores, make sure the submitted programs work.

You will *definitely* receive zero if your program has one or several
syntax error reported by gcc.  There is no exception to this rule in
any circumstance.  Even if your programs would work correctly after
adding a semicolon, you will still receive zero.  Remember that it is
your responsibility submitting a correct program.  

The teaching staff will never modify your program for grading in any
circumstance.  Your score depends on what is submitted.

====================================================================

Some students ask the instructor, "What do you want me to do?"  The
students misunderstand the role of the instructor.  You learn FOR
YOURSELF, not anyone else.  Ask yourself "What should I do to learn
better?"

====================================================================

ECE 264 is a course for you to start writing non-trivial programs.  In
many cases, you should design the programs before you start writing
code.  If you want to spend less time in the programming assignments,
think carefully and design on paper before writing code.  If you start
writing code without clear understanding and careful design, you will
likely spend many more hours than your classmates.