Weekly Journal : Cell Society Project Analysis

You either win or you learn. I always reflect on the things that I could’ve done better, the things we could’ve done better to try and take that next step. — Jalen Hurts (Philadelphia Eagles quarterback who lost in this year's Super Bowl)

This analysis is your opportunity to demonstrate your own thinking and knowledge of design concepts represented (or not) in the project's code. The Teaching Team can readily identify the good and bad aspects of project's design, so we are looking to see if you can also acknowledge these as well. If it is also an honest and thoughtful retrospective, it can also help you identify specific actions you can do to improve future projects.

Submitting Your Work

As a team, complete the following on the master branch of your cellsociety_teamNN repository (no other modifications to this project repository should be made):

• DESIGN Document: complete the doc/DESIGN.md file (note, any part of this document or submitted lab discussions can also be used within your analysis as appropriate)

Individually, complete the following on the master branch of your portfolio_NETID repository:

• cellsociety folder:
  • Example Simulation: make an example simulation and 40-60 second video of it running that shows off something interesting about your project
  • Code Masterpiece: Java file(s), totaling approximately 150-300 lines, that demonstrate well designed code you wrote during the project
• top-level (as usual):
  • a Markdown file, named week06_cellsociety_analysis.md, with your reflection on the project's design based on the questions below

Specifications

Example Simulation

Create your own "interesting" example simulation configuration file(s) and record a 40-60 second video showing it and the result of running it in your project (provide a voice over on the video to describe what makes your example interesting). Go beyond a simple test example or starting configuration to show off important features or design elements by focusing on creative or powerful things your project can do (the video can cover any part of the running simulation, not just beginning after loading it).

The easiest way to make a video of your running project is to start a Zoom call, share your screen, start recording, and talk over your demo. There are also many free screen capture tools available or free trials of commercial tools.

Submit both the video and configuration file(s).

Code Masterpiece

Choose class(es) you primarily wrote that you feel demonstrate good design for us to review in detail.

The code should represent a component within your larger project that is small enough to be separable, but functionally significant enough to have some interesting design element. The term "component" is used rather than "class" because it may be several classes that work together, e.g., a few classes that work together or a superclass and its sub-classes. Note, if your component is specifically intended to be superclass, it must include enough detail that it is clear how to extend it and at least one example subclass to how it supports an abstraction.

• Every line of code in the class(es) you submit will be judged, you cannot specify parts of a class to ignore or include large sections of commented out code
• Add comments to the top of each class included that describe the class's purpose and why you think it is well designed

Simply copy only the Java code files you want us to review from your project to your portfolio, into a folder named cell_society, without renaming them so we can easily compare them to previous versions. You do not have to include files they depend on as we will not be compiling these versions, just reviewing on them.

Your masterpiece code must total between approximately 150-300 lines, including comments.

Design Analysis

Explain your view of how your program is organized and why it was done that way. This is an opportunity to describe how you might fix a problem, conceptualize something you thought about but could not figure out how to implement, present an alternate design you preferred or did not have time to actually refactor the code after learning something new, or any other learning you want to tell us about that the code does not convey.

If you think something is good, justify your opinion. If you think something is bad, justify your opinion and suggest how to improve it. Use specific code examples and supporting reasons related to design principles discussed in class or in the readings rather than general terms like "clearly/obviously", "good/sucks", "elegant/ugly", or "like/hate".

Note, no design is perfect so including both pros and cons (i.e., its trade-offs) or alternate designs you considered is highly encouraged (often designs cannot be seen as better or worse than another, but rather as a specific set of trade-offs that prioritize different goals).

• Overall Design. Reflect on the entire project by reviewing all the code, especially parts you did not write:
  • Discuss the design of the complete program:
    • Describe what is needed to add a new kind of simulation (i.e., all parts of the code that need to be changed to recognize new data files, new Automata rules, or new XML tags)?
    • How do each of the three main parts (Simulation, Configuration, and Visualization) depend on each other (i.e., what classes, behavior, exceptions, data, or resources are required by the other parts)?
      Evaluate two dependencies for each part (six total) — for each, one you feel is good and one you feel could be improved:
      • Is the dependency warranted (e.g., uses most or significant part of the imported class or package it comes from)?
      • Is the dependency clear and easy to find (e.g., public methods and parameters) or done based on "back channels" (e.g., static calls, order of method call, requirements for specific subclass types)?
      • Does the dependency help the code that uses it (e.g., makes the code more readable, hides an important detail, or closes the code) or not (e.g., requires a check for null, a "polymorphic" conditional, or assumption to use correctly)?
    Note, you can use IntelliJ to help you find the dependencies within your project.
  • Describe two examples of code for each of the following concepts — one you feel it embodies that principle or could be improved by applying that principle:
    • Single Responsibility Principle
    • Open-Closed Principle
    • Liskov Substitution Principle
  • Describe two features from the assignment specification — one you feel was made easier to implement by the code's design and one you feel could have been easily implemented due to the current design.
    • Be as specific as possible about how existing abstractions and methods are helpful
  • Review two features in detail implemented primarily by your teammates — one you feel is good and one you feel could be improved:
    • Describe this feature's design in detail (what parts are closed? what implementation details are encapsulated? what assumptions are made? etc.)
    • Evaluate this feature's design (justifying why you feel it is good or explaining how you would improve it)
  • Conclusion: Describe what you think makes this project's overall design flexible or not (such as what new changes does it support making easily)
• Your Design. Reflect on the coding details of your part of the project:
  
• Discuss any Code Design Habit Checklist issues within your code (justify why they do not need to be fixed or describe how they could be fixed if you had more time).
  Note, the checklist tool used in the last lab can be useful in automatically finding many checklist issues.
• Describe one abstraction (either inheritance hierarchy or class that uses polymorphism effectively) you created (or wish you had) and how it helped (or would have helped) the design.
• Describe one design challenge you wrestled with:
  • What alternate designs were considered?
  • What are the trade-offs of all the design options (describe the pros and cons of the different designs)?
  • How did you eventually handle it?
  • Why are you satisfied or not with the final solution (i.e., in hindsight do you wish it could have been done differently due to how it made coding more difficult, based on the course readings, etc.)?
• Review two features you implemented in detail — one you feel is well designed and one whose design could be improved:
  • Describe this feature's design in detail (what parts are closed? what implementation details are encapsulated? what assumptions are made? etc.)
  • Evaluate this feature's design, justifying why you feel it is good or explaining how you would improve it
• Conclusion: Describe your specific efforts to make your code as encapsulated or abstract as possible.
• Alternate Designs. Reflect on alternate designs for the project based on your analysis of the current design or project discussions.
  • Describe which classes would be affected by changing the Grid's data structure (say from a 2D array to a Map or vice versa).
  • Describe how well (or poorly) the original design handled the project's Change specifications and how they were discussed and decisions ultimately made.
  • Describe one assumption or choice made about the assignment specifications or the code that had a global or significant impact on the design.
  • Review two design decisions discussed by the team about any part of the program in detail:
    • What alternate designs were considered?
    • What are the trade-offs of all the design options (describe the pros and cons of the different designs)?
    • Which did you prefer and why (it does not have to be one that is currently implemented)?
    • Why are you satisfied or not with the final solution (i.e., in hindsight do you wish it could have been done differently due to how it made coding more difficult, based on the course readings, etc.)?
  • Conclusion: Describe what kinds of things you think affect whether a choice can be encapsulated or will impact the overall design.
• Conclusions. Reflect on what you have learned about designing programs through this project:
  
  • Describe two coding habits you noticed this project — one that has changed for the better and one you are still working on changing
  • How has the act of refactoring code felt? Are the goals clear and is it making a positive impact? Give a specific example (either positive or negative).
  • What have you learned about design by reading your team mates' code or by Pair Programming? Give a specific example (either positive or negative).
  • How has your perspective on the practice of coding changed because of this project?
  • What specific steps can you take to become a better designer in the next project?