Category Archives: Week 10

Best Practices For Software Documentation

For this week’s blog, I decided to research a bit about documentation standards. I recall working on a lot of documentation for a project in the summer so I wanted to find any blogs that can help me write better documentation. The blog that I found to be particularly helpful is “Software Documentation Best Practices” by David Oragui. In his blog he touches on what software documentation is, types of software documentation, the benefits of creating it, and how to write effective documentation.

Software documentation provides information about software products and systems. The several categories and types will depend on the audience and intended use of the software. The types of software documentation that were discussed were those for end users, developers, as well as system administrators, and other IT professionals. The documentation for end users provides step-by-step instructions for common tasks and describes the features and capabilities of the software. The documentation for developers and other technical stakeholders provides technical information about the software like its API, data structures, or algorithms. The documentation for system administrators and other IT professionals includes installation guides. The breakdown of what each audience would need is very helpful to gain a deeper understanding of the topic. 

The section that explained the benefits of creating software documentation aided in my understanding of its importance. The benefits that were mentioned are improved user experience, enhanced collaboration, increased efficiency, and improved quality. Improved user experience is an obvious benefit but I didn’t think about the other benefits that were mentioned. Now that I’ve read the blog, I understand how it makes the development process consistent and helps developers work more efficiently because the necessary information is easily accessible.

I also found the section about writing effective software documentation extremely helpful. The tips that were included are: (1) Prioritize Documentation in the Development Process, (2) Identify Your Target Audience,  (3) Define the Scope and Goals, (4) Develop a Content Strategy, (5) Create a Style Guide, (6) Write Clearly and Concisely, and (7) Review and Revise. The additional best practices that he included at the end were extremely useful as well. The tips for including examples and exercises, using a consistent structure and format, and ensuring inclusivity and accessibility are very important. I found many of the tips to be familiar. While working on software in the summer, the team I was working with made sure to follow a style guide and include examples. After we split up to write the documentation for different tools, we made sure to have another set of eyes for review. We also used tools to detect gendered and biased language.

Although I am somewhat familiar with software documentation best practices, reading through useful information on the topic helped solidify what I already knew and provided me with new knowledge to put into practice. 

From the blog CS@Worcester – Live Laugh Code by Shamarah Ramirez and used with permission of the author. All other rights reserved by the author.

Week-10 Post

This podcast by All The Code discusses the use of GitHub and GitLab APIs for managing software development projects. The host of the podcast conveyed his disdain for GitHub’s API when he was involved in a project that utilized GitHub to share images and video links. Users had to request access to the repository in order to access the content, which the speaker did not like. He emphasized that requesting access on GitHub isn’t user friendly to someone who isn’t experienced with the site. When the hosts talked about GitLab, they described the platform as “amazing” and its ability to do “wonderful stuff”. Additionally, The speakers compared both GitHub and GitLab’s documentation and found GitLab to be the all around better platform documentation wise. Lastly, the podcast hosts argue that GitHub is ideal for large companies as GitLab is suited for smaller companies/teams. I chose this specific podcast because I have worked with both GitHub and GitLab in this class and can’t seem to prefer one over the other. I will say that I was more comfortable with traversing GitHub compared to GitLab. Although GitLab is considered to be easier to navigate, I often find myself struggling to access projects and repositories in different groups within GitLab. I’m hoping as time comes, I will get more comfortable with navigating the platform. This podcast has changed my view on GitLab, knowing that GitLab is more user friendly with documentation is extremely important to consider when choosing which platform to use mainly. Of course, companies will expect their teams to use the same platform to prevent any conversion issues. Having solid documentation in your software development projects is vital so new developers/users can easily understand the project and its goal. Going forward with this information, I will experiment with the various features GitLab has to offer regarding documentation. For example, GitLab has a feature called GitLab Flavored Markdown (GLFM) which gives you the ability to render certain text with a style. GitLab Flavored Markdown allows you the change the color of text, add emojis, create detailed lists, and more.

Selected Podcast: https://www.youtube.com/watch?v=LsRZiWPPiEQ&ab_channel=AllTheCode

From the blog CS@Worcester – Computer Science Through a Junior by Winston Luu and used with permission of the author. All other rights reserved by the author.

Git and Game Development

     A subject that has always been near and dear to my heart is video games. Throughout my life I have always been deeply enamored with games and the process of their creation, from the intricacies of 3d modeling to the various game engines in use. Despite that, I would not say I am an expert in modern game development by any means. As my classes have progressed however, I have begun to understand more about the inner workings of software development and how teams are managed. This led me to investigate how game developers use these tools to manage projects and keep everything orderly. After doing some research, I found that many game engines are compatible with git and have no issue being stored on GitHub. Not only that but prominent game engines like Unreal Engine even have their source code up on GitHub, available for anyone to fork and clone. This was done to allow developers to modify the game engine itself, for whatever purposes they need. Godot is a free open-source engine that uses the MIT license and is also entirely up on GitHub. Of course, even if an engine does not have their code on GitHub or Gitlab that does not mean you cannot just host your code in an online repository. Thanks to what I have learned this semester, I can now make use of GitHub in the creation of repositories for any game projects I have. 

  It is not enough to learn about how game developers make use of git, project management is also a vital tool for game development. In terms of project frameworks, agile methodologies have seen widespread use within various industries, including the video game industry. Scrum is the most prominent of these methodologies and has been adopted by various companies. Due to the nature of video game development, there is a greater need for cross-disciplined teams comprised of developers versed in various skills. Game development can be effectively chopped up into tasks that fit nicely into each increment, for the medium itself necessitates a functioning step by step pipeline. Level designers cannot do anything without the assets created by artists and so on and so forth. The first couple sprints would work on creating functional assets like 3D models, textures, and game mechanics. The goal of each subsequent sprint would be to create a functional game section by section. I hope to one day make use of scrum and help create a game of my own.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

Git and Game Development

     A subject that has always been near and dear to my heart is video games. Throughout my life I have always been deeply enamored with games and the process of their creation, from the intricacies of 3d modeling to the various game engines in use. Despite that, I would not say I am an expert in modern game development by any means. As my classes have progressed however, I have begun to understand more about the inner workings of software development and how teams are managed. This led me to investigate how game developers use these tools to manage projects and keep everything orderly. After doing some research, I found that many game engines are compatible with git and have no issue being stored on GitHub. Not only that but prominent game engines like Unreal Engine even have their source code up on GitHub, available for anyone to fork and clone. This was done to allow developers to modify the game engine itself, for whatever purposes they need. Godot is a free open-source engine that uses the MIT license and is also entirely up on GitHub. Of course, even if an engine does not have their code on GitHub or Gitlab that does not mean you cannot just host your code in an online repository. Thanks to what I have learned this semester, I can now make use of GitHub in the creation of repositories for any game projects I have. 

  It is not enough to learn about how game developers make use of git, project management is also a vital tool for game development. In terms of project frameworks, agile methodologies have seen widespread use within various industries, including the video game industry. Scrum is the most prominent of these methodologies and has been adopted by various companies. Due to the nature of video game development, there is a greater need for cross-disciplined teams comprised of developers versed in various skills. Game development can be effectively chopped up into tasks that fit nicely into each increment, for the medium itself necessitates a functioning step by step pipeline. Level designers cannot do anything without the assets created by artists and so on and so forth. The first couple sprints would work on creating functional assets like 3D models, textures, and game mechanics. The goal of each subsequent sprint would be to create a functional game section by section. I hope to one day make use of scrum and help create a game of my own.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

Git and Game Development

     A subject that has always been near and dear to my heart is video games. Throughout my life I have always been deeply enamored with games and the process of their creation, from the intricacies of 3d modeling to the various game engines in use. Despite that, I would not say I am an expert in modern game development by any means. As my classes have progressed however, I have begun to understand more about the inner workings of software development and how teams are managed. This led me to investigate how game developers use these tools to manage projects and keep everything orderly. After doing some research, I found that many game engines are compatible with git and have no issue being stored on GitHub. Not only that but prominent game engines like Unreal Engine even have their source code up on GitHub, available for anyone to fork and clone. This was done to allow developers to modify the game engine itself, for whatever purposes they need. Godot is a free open-source engine that uses the MIT license and is also entirely up on GitHub. Of course, even if an engine does not have their code on GitHub or Gitlab that does not mean you cannot just host your code in an online repository. Thanks to what I have learned this semester, I can now make use of GitHub in the creation of repositories for any game projects I have. 

  It is not enough to learn about how game developers make use of git, project management is also a vital tool for game development. In terms of project frameworks, agile methodologies have seen widespread use within various industries, including the video game industry. Scrum is the most prominent of these methodologies and has been adopted by various companies. Due to the nature of video game development, there is a greater need for cross-disciplined teams comprised of developers versed in various skills. Game development can be effectively chopped up into tasks that fit nicely into each increment, for the medium itself necessitates a functioning step by step pipeline. Level designers cannot do anything without the assets created by artists and so on and so forth. The first couple sprints would work on creating functional assets like 3D models, textures, and game mechanics. The goal of each subsequent sprint would be to create a functional game section by section. I hope to one day make use of scrum and help create a game of my own.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

Git and Game Development

     A subject that has always been near and dear to my heart is video games. Throughout my life I have always been deeply enamored with games and the process of their creation, from the intricacies of 3d modeling to the various game engines in use. Despite that, I would not say I am an expert in modern game development by any means. As my classes have progressed however, I have begun to understand more about the inner workings of software development and how teams are managed. This led me to investigate how game developers use these tools to manage projects and keep everything orderly. After doing some research, I found that many game engines are compatible with git and have no issue being stored on GitHub. Not only that but prominent game engines like Unreal Engine even have their source code up on GitHub, available for anyone to fork and clone. This was done to allow developers to modify the game engine itself, for whatever purposes they need. Godot is a free open-source engine that uses the MIT license and is also entirely up on GitHub. Of course, even if an engine does not have their code on GitHub or Gitlab that does not mean you cannot just host your code in an online repository. Thanks to what I have learned this semester, I can now make use of GitHub in the creation of repositories for any game projects I have. 

  It is not enough to learn about how game developers make use of git, project management is also a vital tool for game development. In terms of project frameworks, agile methodologies have seen widespread use within various industries, including the video game industry. Scrum is the most prominent of these methodologies and has been adopted by various companies. Due to the nature of video game development, there is a greater need for cross-disciplined teams comprised of developers versed in various skills. Game development can be effectively chopped up into tasks that fit nicely into each increment, for the medium itself necessitates a functioning step by step pipeline. Level designers cannot do anything without the assets created by artists and so on and so forth. The first couple sprints would work on creating functional assets like 3D models, textures, and game mechanics. The goal of each subsequent sprint would be to create a functional game section by section. I hope to one day make use of scrum and help create a game of my own.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

Git and Game Development

     A subject that has always been near and dear to my heart is video games. Throughout my life I have always been deeply enamored with games and the process of their creation, from the intricacies of 3d modeling to the various game engines in use. Despite that, I would not say I am an expert in modern game development by any means. As my classes have progressed however, I have begun to understand more about the inner workings of software development and how teams are managed. This led me to investigate how game developers use these tools to manage projects and keep everything orderly. After doing some research, I found that many game engines are compatible with git and have no issue being stored on GitHub. Not only that but prominent game engines like Unreal Engine even have their source code up on GitHub, available for anyone to fork and clone. This was done to allow developers to modify the game engine itself, for whatever purposes they need. Godot is a free open-source engine that uses the MIT license and is also entirely up on GitHub. Of course, even if an engine does not have their code on GitHub or Gitlab that does not mean you cannot just host your code in an online repository. Thanks to what I have learned this semester, I can now make use of GitHub in the creation of repositories for any game projects I have. 

  It is not enough to learn about how game developers make use of git, project management is also a vital tool for game development. In terms of project frameworks, agile methodologies have seen widespread use within various industries, including the video game industry. Scrum is the most prominent of these methodologies and has been adopted by various companies. Due to the nature of video game development, there is a greater need for cross-disciplined teams comprised of developers versed in various skills. Game development can be effectively chopped up into tasks that fit nicely into each increment, for the medium itself necessitates a functioning step by step pipeline. Level designers cannot do anything without the assets created by artists and so on and so forth. The first couple sprints would work on creating functional assets like 3D models, textures, and game mechanics. The goal of each subsequent sprint would be to create a functional game section by section. I hope to one day make use of scrum and help create a game of my own.

https://www.unrealengine.com/en-US/ue-on-github

https://www.gamedeveloper.com/production/agile-game-development-with-scrum-teams

https://starloopstudios.com/best-agile-practices-in-game-development/

From the blog CS@Worcester Alejandro Professional Blog by amontesdeoca and used with permission of the author. All other rights reserved by the author.

CS-343 Week 10

GRASP (General Responsibility Assignment Software Patterns) assigns responsibilities for different modules of code in object-oriented software development. There are seven types of roles assigned to classes and objects to easily organize the responsibilities. These roles include Controller, Information Expert, Creator, High Cohesion, Low Coupling, Polymorphism, and Protected Classes. It is important to note that GRASP is occasionally paired with SOLID principles, making for the combination SOLID GRASP. Design patterns like this help keep code clean and more organized, making it more comprehensible and reusable.

Controller suggests that the entity responsible for handling a system operation should be its own class to act as an intermediary between the user interface and the logic of the program. This helps separate concerns as well as improve flexibility of the whole system. Information Expert focuses on assigning responsibilities to classes that include the most information required to fulfill them. By following this principle, we can design systems where responsibilities are distributed efficiently amongst classes which in turn reduces dependencies. Creator guides the allocation of responsibility for creating objects. A class should be responsible for creating objects of other classes if the first class aggregates or has a composition relationship with the second class. By following this, there will be less coupling between classes and ensures better maintainability. High cohesion advocates designing classes with a clear and focused purpose. Each class should have a single responsibility and capture related behaviors and data. This provides easier comprehension of the code and simpler test cases to write. Low Coupling relies on designing classes with minimal dependencies on other classes. The less interconnections between classes allows to create a more modular system and improves maintainability since changes to one class are less likely to affect other classes. Polymorphism enables objects of different classes to be treated the same throughout a common interface in object-oriented design. Leveraging this principle allows for the design of systems to be extensible and adaptable to new requirements and promotes loosely coupled systems.

Applying GRASP principles ensures a clear distribution of responsibilities and promotes low coupling and high cohesion among classes. These principles help create an understandable design architecture while also providing the ability to adapt to future changes. This also helps team members collaborate due to better facilitation for communication among developers and it establishes a common understanding of each component’s role and interactions.

What is GRASP (General Responsibility Assignment Software Patterns)? | Definition from TechTarget

GRASP Principles: Object-Oriented Design Patterns | by Patrick Karsh | Medium

From the blog CS@Worcester – Jason Lee Computer Science Blog by jlee3811 and used with permission of the author. All other rights reserved by the author.

Should we still use SOLID Principles?

While I was perusing for an article to write about this week I found this interesting blog post posing the question, “Why SOLID principles are still the foundation for modern software architecture”. The post is written by Daniel Orner, a Software engineer from the likes of Flipp and formerly IBM.

Daniel starts by explaining what exactly is “SOLID”, he attributes the meaning of SOLID to “the writings of Robert C. Martin in the early 2000s” which provided a framework for creating quality object-oriented programs.

Daniel then covers what has changed since the 2000s but also what hasn’t. Things that have changed are the popularity of scripting or dynamic languages has risen greatly, some facets of object-oriented programming have become meshed with functional programming, open source software has become extremely popular, and microservices have seen massive growth in use since the 2000s.

However, things that haven’t changed are that programs are still written and modified by people, there is still a form of organization/separation of code regardless of the language used, and code can be used for either internal or external purposes. I believe that all of these facets of programming may never change no matter how much time passes. Even with the advancement of AI, I still believe that the human factor in programming will always be important. When faced with potential moral or ethical problems, a human element would always result in a better outcome than an AI could/would.

Daniel then goes through each of the five principles and alters them to become more general and applicable to modern programming trends. He starts by altering the single responsibility principle to “Each module should do one thing and do it well.”, the open-closed principle to “You should be able to use and add to a module without rewriting it.”, the Liskov substitution principle to “You should be able to substitute one thing for another if those things are declared to behave the same way.”, the interface segregation principle to “Don’t show your clients more than they need to see.”, and finally he left the dependency inversion principle as is!

Daniel then wraps up his post concluding that modern SOLID is ensuring that your code is not surprising or confusing to anyone who will use or work with it, keeping things reasonable, and properly organizing said code. Reiterating that SOLID is still key to creating and maintaining well-written code.

Overall, after reading Daniel’s post it allowed me to widen my view and understanding of the solid principles. After comparing his new definitions to the ones crafted by Robert Martin, it showed how well thought out SOLID principles were to be able to last 20+ years already and remain relevant for plenty more to come. The SOLID principles offer a framework not only for object-oriented programming but programming in general and Daniel showed this impeccably just by changing a couple of words in the definitions while keeping the same meanings given to the principles back in the 2000s.

Article Link: https://stackoverflow.blog/2021/11/01/why-solid-principles-are-still-the-foundation-for-modern-software-architecture/

From the blog CS@Worcester – Eli's Corner of the Internet by Eli and used with permission of the author. All other rights reserved by the author.

11/18 – Keeping the ball rolling.

So, since the end of the semester is coming up, I should be posting weekly for the near future, so stay tuned for a lot from me! With this week of work, I have two topics I wanted to discuss, both related to each class I’m taking with Professor Wurst.

Firstly, on the Software Process Management side, I wanted to discuss how we’re using Scrum, and the way it’s set up. We’re using GitLab’s issue boards, dividing them amongst where they currently are in The Sprint, with stuff like the Issue Backlog, In Process, Needs Review, Finished, and so on so forth.

This setup reminded me a hell of a lot of Trello, a website/service I’ve been using for years now! And what’s funny is that I even mentioned this in class once, and the Professor said he used to as well for Scrum. My setup is quite different compared to the setup we have on GitLab, however, it still uses a similar Scrum/Kanban-esque setup.

Here’s the two boards I mainly use, one for School, and one for Commission work, as I freelance in art. With my Comm board, it is a bit more simpler, having using tags within lists as opposed to using a list per tag. As for my schoolwork board, it’s simply just listed with each course I’m taking and items of work I need to finish. It’s a very good tool, and I highly suggest it to anyone looking to utilize Scrum or even need a good tool to organize things.

Check it out here! https://trello.com/

As for the Software Design, I was curious what kind of file the .json’s we were using were. We have been using them to store data about students and members of the modified version of LibreFoodPantry’s backend. I’ve seen them used before many times in my times modding games before, usually they store data for configuration files.

So, to learn more, I found this blog from HubSpot: https://blog.hubspot.com/website/json-files, and honestly I think I get it a bit more now. They’re simply data storage files, able to store comma seperated values, objects, and arrays. They also support multiple data types, like integer, boolean, and strings.

So putting that into the context of configuration files, like for settings in games, it makes sense why they are used, due to integer and boolean values. If an option for a game has an on/off choice, a boolean data value to hold that information would make sense, as “true” would be on, and “false” would be off. As for how integers would be used, say you want to store the value of the volume the user wants while playing the game, that can be stored as an integer from 0-100.

All in all, it’s really interesting to learn more about filetypes I don’t know too much about, and I should look into more and how they are written, like .obj, .html, and .ini.

From the blog CS@Worcester – You're Telling Me A Shrimp Wrote This Code?! by tempurashrimple and used with permission of the author. All other rights reserved by the author.