Skip to content

Commit 74eb762

Browse files
marissaschmidtmarissaschmidt
committed
Adding sample README's
1 parent 719e944 commit 74eb762

File tree

4 files changed

+311
-0
lines changed

4 files changed

+311
-0
lines changed

‎etext.zip renamed to ‎etext/etext.zip

File renamed without changes.

‎projects/README.example

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
*******************************************************************************
2+
* Project: 1-Animated Marshmallow
3+
* Class: CS 121 section 2
4+
* Date: September 23, 2014
5+
* Name: Sami Stoodent
6+
*******************************************************************************
7+
8+
PROJECT OVERVIEW:
9+
10+
This Java application displays an animated marshmallow with features based on
11+
user input specifying sponginess, color, sugar density, and burn resistance.
12+
13+
14+
INCLUDED FILES:
15+
16+
* README - this file
17+
* Marshmallow.java - the main source code
18+
19+
20+
BUILDING AND RUNNING:
21+
22+
All project files should be in the same directory.
23+
24+
From the directory containing the .java source code, compile the program:
25+
$ javac Marshmallow.java
26+
27+
Run the program from the directory containing Marshmallow.class:
28+
$ java Marshmallow
29+
30+
You will be prompted for integer values representing distance to the fire,
31+
fire intensity, marshmallow burn resistance, and marshmallow sugar density.
32+
33+
34+
PROJECT DESIGN:
35+
36+
The Marshmallow class extends the JPanel class, so it has all of the
37+
properties and methods of a JPanel - this class basically just overwrites
38+
the JPanel paintComponent() method and includes a Timer and ActionListener
39+
to update and refresh the panel by periodically calling paintComponent()
40+
indirectly via the repaint() method. Because main() creates the JFrame and
41+
an instance of Marshmallow, this class is self-contained and there is no
42+
separate driver class.
43+
44+
After JPanel, the classes that were the focal points of this program were
45+
the Timer and Graphics classes. The Timer code was given to us. Most of
46+
the work for this program centered around the Graphics class and its many
47+
draw and fill methods.
48+
49+
All graphic elements are drawn relative to a single anchor point for ease
50+
of relocating as the canvas is resized. The marshmallow is centered in the
51+
view and sized so that it occupies 50% of the lesser of the width and height.
52+
Text output is also resized to ensure it fits within the view and doesn't
53+
cover the marshmallow.
54+
55+
Each of the user input parameters uses a separate input dialog box. It
56+
works, but it seems clunky. I think it would be better if there was one form
57+
at the beginning with all the choices, but I'm not sure how to do something
58+
like that yet.
59+
60+
I originally intended to make the animation refresh rate adjustable, but ran
61+
out of time. The hardcoded refresh rate looks good on my local machine, but
62+
it's too fast when viewing the animation over a remote connection, so this
63+
feature would be a good addition to the project.
64+
65+
66+
PROJECT DEVELOPMENT AND TESTING DISCUSSION:
67+
68+
When I realized my paintComponent() method was getting really long and hard to
69+
read, I broke out each graphical element into its own private method. The hard
70+
part of that was figuring out that I needed to pass in the Graphics object to
71+
each method, but it worked well after I did that. It also helped to read about
72+
the Graphics class in the Java API, to learn how to use the different draw
73+
methods.
74+
75+
I tested values from 0 to 20 for each of the input parameters, but I found that
76+
values greater than 20 cause the program to freeze up. I don't know how to
77+
restrict input values, yet, but that would be a good feature to add. I added
78+
a warning to the input dialog, but there's nothing to stop users from adding
79+
values over 20.
80+
81+
I tried running the program remotely over SSH with X, but my connection wasn't
82+
fast enough to see the animation very well and there were several times the
83+
dialog boxes for my input prompts showed up behind the main window. When I
84+
came into the lab and ran it, however, everything looked good and worked just
85+
like it did when I ran it locally on my own computer.
86+
87+
The starting file for the project had a window size of 200 x 500, but I found
88+
that the text was too small to read unless the height was at least 300, so I
89+
ended up with minimum dimensions of 300 x 500. It looks best, though, even
90+
bigger. I recommend 400 x 600.
91+
92+
This project was challenging at first, but it was fun once I got the hang of
93+
it and I feel like I learned a lot about graphics in Java.
94+
95+
96+
EXTRA CREDIT:
97+
98+
I added the flame animation and screaming sound effect when the marshmallow
99+
overheats. You can see it when sugar density is > 10 and burn resistance is
100+
< 15.

‎projects/README.example2

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
****************
2+
* ArraySet
3+
* CS 221
4+
* 12/25/2050
5+
* Sam Student
6+
****************
7+
8+
OVERVIEW:
9+
10+
ArraySet is an array-based implementation of the SimpleSet ADT,
11+
supporting basic set collection functionality.
12+
SetTester confirms that ArraySet is a valid, fully functional
13+
SimpleSet.
14+
15+
16+
INCLUDED FILES:
17+
18+
SimpleSet.java - source file
19+
ArraySet.java - source file
20+
ElementNotFoundException.java - source file
21+
SetTester.java - source file
22+
README - this file
23+
24+
25+
BUILDING AND RUNNING:
26+
27+
From the directory containing all source files, compile the test
28+
class (and all dependent classes) with the command:
29+
$ javac SetTester.java
30+
31+
Run the compiled SetTester class with the command:
32+
$ java SetTester
33+
34+
Console output will report which tests ArraySet passed or failed.
35+
36+
37+
PROGRAM DESIGN:
38+
39+
ArraySet implements the SimpleSet interface, which defines methods for a
40+
basic set collection. ArraySet, as the name implies, manages set elements
41+
in an array. A set only contains one unique instance of an element, so
42+
ArraySet only adds an element if it is not already in the array. Removing
43+
an element will only succeed if the element is found. Attempts to remove
44+
an element not in the set results in an ElementNotFoundException being
45+
thrown.
46+
47+
As the underlying array capacity may not be the same size as the number of
48+
elements in the set, the array is maintained with the first element at
49+
index 0 and with no gaps between elements. The next available index is
50+
used to indicate the current size of the set and to recognize when the
51+
array is not large enough to hold a new element.
52+
53+
When the array capacity needs to be increased, a new array is created,
54+
twice the capacity of the old array, and all elements are copied into
55+
the new array. The reverse is not true, however. As elements are removed,
56+
smaller arrays do not replace larger arrays. If memory use ever becomes
57+
an issue, it may be worth modifying ArraySet to shrink when there is
58+
excessive unused capacity.
59+
60+
SetTester confirms correct operation of all SimpleSet methods for change
61+
scenarios involving sets from zero to three elements after add and
62+
remove changes. It is configured to use the ArraySet implementation of
63+
SimpleSet.
64+
65+
66+
TESTING:
67+
68+
SetTester was the primary mechanism for testing ArraySet. SetTester was
69+
written before ArraySet, so test-driven development helped ensure that
70+
all ArraySet functionality was being tested from the start.
71+
72+
Scenarios being tested by SetTester include:
73+
a new empty set
74+
adding the first element to an empty set
75+
removing the element from a one element set
76+
adding a duplicate element to a set with one element
77+
adding a second element to a set with one element
78+
removing each of the two elements in a two element set
79+
adding a third element to a two element set
80+
removing each of the three elements from a three element set
81+
82+
Additional scenarios would be beneficial, such as adding duplicates to
83+
sets with multiple elements, but time did not permit more extensive
84+
testing.
85+
86+
Not all tests are currently passing, but work is still underway to fix
87+
remaining bugs.
88+
89+
90+
DISCUSSION:
91+
92+
Test-driven development was a new idea, for me, and I was a little
93+
skeptical that it would make a difference, but it did help me catch a
94+
couple of bugs early on having to do with my rear index and with
95+
expanding the array capacity that I would have missed. Since ArrayList
96+
still isn't bug free, I'm glad I don't have those problems in there at
97+
the same time!
98+
99+
Working with shifting elements is also a challenge. I think I have the
100+
idea down, but implementing it can still be difficult. I'm starting to
101+
see why everyone suggests drawing pictures of the processes before
102+
coding, to make sure the order of statements actually makes sense.
103+
104+
I haven't made extensive use of the Eclipse debugger, yet, but I think I
105+
need to start using it to figure out my remaining bugs. Reading the code
106+
over and over isn't helping, anymore, and I don't want to fill my code
107+
with print statements I'll just have to rip out, again, later.
108+
109+

‎projects/README.overview

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
****************
2+
* Project number/name
3+
* Class
4+
* Date
5+
* Your name
6+
****************
7+
8+
OVERVIEW:
9+
10+
Concisely explain what the program does. If this exceeds a couple
11+
of sentences, you're going too far. The details go in other
12+
sections.
13+
14+
15+
INCLUDED FILES:
16+
17+
List the files required for the project with a brief
18+
explanation of why each is included.
19+
20+
e.g.
21+
* Class1.java - source file
22+
* Class2.java - source file
23+
* README - this file
24+
25+
26+
COMPILING AND RUNNING:
27+
28+
Give the command for compiling the program, the command
29+
for running the program, and any usage instructions the
30+
user needs.
31+
32+
These are command-line instructions for a system like onyx.
33+
They have nothing to do with Eclipse or any other IDE. They
34+
must be specific - assume the user has Java installed, but
35+
has no idea how to compile or run a Java program from the
36+
command-line.
37+
38+
e.g.
39+
From the directory containing all source files, compile the
40+
driver class (and all dependencies) with the command:
41+
$ javac Class1.java
42+
43+
Run the compiled class file with the command:
44+
$ java Class1
45+
46+
Console output will give the results after the program finishes.
47+
48+
49+
PROGRAM DESIGN AND IMPORTANT CONCEPTS:
50+
51+
Explain the main concepts and organization of your program so that
52+
the reader can understand how your program works. This is not a repeat
53+
of javadoc comments or an exhaustive listing of all methods, but an
54+
explanation of the critical algorithms and object interactions that make
55+
up the program.
56+
57+
If your program has multiple classes, explain the main responsibilities
58+
of each class. Explain how the classes work together to achieve the
59+
program goals. If there are important interfaces, explain their roles
60+
as well.
61+
62+
If you were responsible for designing the program's classes and choosing
63+
how they work together, why did you design the program this way? What, if
64+
anything, could be improved?
65+
66+
This is the sort of information someone who really wants to
67+
understand your program - possibly to make future enhancements -
68+
would want to know.
69+
70+
TESTING:
71+
72+
How did you test your program to be sure it works and meets all of the
73+
requirements? Can your program handle bad input? Is your program
74+
idiot-proof? How do you know? What are the known issues / bugs
75+
remaining in your program?
76+
77+
78+
DISCUSSION:
79+
80+
Discuss the issues you encountered during programming (development)
81+
and testing. What problems did you have? What did you have to research
82+
and learn on your own? What kinds of errors did you get? How did you
83+
fix them?
84+
85+
What parts of the project did you find challenging? Is there anything
86+
that finally "clicked" for you in the process of working on this project?
87+
88+
89+
EXTRA CREDIT:
90+
91+
If the project had opportunities for extra credit that you attempted,
92+
be sure to call it out so the grader does not overlook it.
93+
94+
95+
----------------------------------------------------------------------------
96+
97+
All content in a README file is expected to be written in clear English with
98+
proper grammar, spelling, and punctuation. If you are not a strong writer,
99+
be sure to get someone else to help you with proofreading. Consider all project
100+
documentation to be professional writing for your boss and/or potential
101+
customers.
102+

0 commit comments

Comments
 (0)