Weekly Journal : Cell Society Project Analysis

Reflection without action is ultimately as unproductive as action without reflection. — Robert Kegan

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 recognize 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 main 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 main branch of your portfolio_NETID repository:

• cellsociety folder:
  • Example Simulation: make a new example simulation and 40-60 second video of it running that shows off something interesting about your project
  • Code Masterpiece: choose Java file(s) that demonstrate well designed code you wrote during the project, totaling approximately 150-300 lines
• journal folder:
  • a Markdown file, named week11_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 subclass as an example of how it implements the 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 submitted that describe the class's purpose and justify why you think it is well designed

Simply copy without renaming the Java code files you want us to review to your portfolio repository, into a folder named cell_society, so we can easily compare them to previous versions. You do not have to include any files they may depend on as we will just review them, not compile them.

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

Design Analysis

This document is vital, as it is your opportunity to:

• explain your design decisions
• 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 if you did not have time to refactor the code after learning something new
• show any other learning 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 each of the following (include all parts of the code or resources that need to be changed or to recognize new data files):
      • a new kind of simulation
      • new view to the front end
      • any feature from the specification that was not implemented
    • Describe how each of the three main modules (Simulation, Configuration, and Visualization) depend on each other (i.e., what classes, behavior, exceptions, data, or resources are required by the other parts).
      Note, you can use IntelliJ to help you find the dependencies within your project.
    • Evaluate two communication-oriented classes — one you feel is good and one you feel could be improved:
      • How does its type (e.g., Record, Interface, Abstract Class, Immutable Class, Concrete class, etc.) help show its intent and provide value to the design.
      • Is its use 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 it 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)?
  • 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:
    • Open-Closed Principle
    • Interface Segregation Principle
    • Dependency Inversion Principle
  • Review two features by their ID 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 by referencing specific Design Requirement ID(s) (justifying why you feel it is good or explaining how you would improve it)
  • Review one API abstraction designed primarily by your teammates:
    • What makes it encapsulated or not (i.e., can the implementation be easily changed without affecting the rest of the program)?
    • What makes it easy to use and hard to misuse or not (i.e., do classes and methods do what you expect and have logic that is clear and easy to follow)?
    • In what ways does it provide for extension or not (i.e., how does it close its algorithm and promote users to create new functionality)?
  • 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 Static Code Analysis Issues remaining in code you wrote (justify why they do not need to be fixed or describe how they could be fixed if you had more time).
• Describe one design challenge you wrestled with:
  • What abstraction (either inheritance hierarchy or class that uses polymorphism effectively) did you create (or wish you had) and how it helped (or would have helped) the design?
  • 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 one API abstraction you designed or contributed to:
  • What makes it encapsulated or not (i.e., can the implementation be easily changed without affecting the rest of the program)?
  • What makes it easy to use and hard to misuse or not (i.e., do classes and methods do what you expect and have logic that is clear and easy to follow)?
  • In what ways does it provide for extension (or not) (i.e., how does it close its algorithm and promote users to create new functionality)?
• Review two features by their ID 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 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 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:
  
  • How has your thinking about using GIT changed during this project or in a team? Give examples of specific focused commits (e.g., Test, Refactor, Bug fix, etc.).
  • 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).
  • How has thinking about public methods as APIs felt? Is it making a positive impact on how you conceptualize your code? Give a specific example (either positive or negative).
  • How has making your code data driven or at least removing the hardcoded values felt? When during the process of coding are you incorporating data files? 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?

Your analysis must cite specific code examples from the project and citations from the course readings.