For this week’s blog post, I chose the article “Code Documentation: How to Do It Right” by the editorial team of SkillReactor. I chose this article in particular because it aligns well with the code documentation section of the syllabus. This article goes into great depth about code documentation and its benefits, as well as how it is best implemented. In this blog post, I will specifically be going over the code documentation tools discussed in the article and how the article discusses overcoming documentation challenges. Prior to reading this article, I wasn’t very familiar with code documentation tools, but I learned much about their function and how some of the tools mentioned can be used with multiple programming languages.

The article mentions a few specific code documentation tools that are commonly used in software development. One of the tools mentioned that caught my attention is Doxygen. “Doxygen is a versatile tool that supports multiple programming languages and generates documentation in HTML, LaTeX, and RTF formats.” Doxygen is very interesting because of its benefit of functioning alongside multiple programming languages and creating documentation in HTML, which, in my experience, can be very difficult to navigate without some form of documentation guiding you. I also found Sphinx to be fascinating because the article mentions that it makes use of automated API documentation generation. “Sphinx, primarily used for Python codebases, offers automated API documentation generation and support for reStructuredText markup language.” This tool having the capability to generate documentation for your code automatically can be immensely helpful; it being automatically generated can also help with accidentally using jargon or slang that may not be understood by others reading through your code. Another essential aspect that the article discusses is overcoming some challenges associated with creating code documentation.

Writing documentation into your code comes with great benefits, but often, it can be difficult to implement into your project. One of these challenges being maintaining up to date documentation with a project. “Although code documentation offers numerous advantages, it comes with its own set of challenges. Managing updates to documentation can be a daunting task, particularly in large projects where multiple developers are working simultaneously.” Another challenge that comes along with creating documentation is avoiding redundancy. “Another challenge is avoiding redundancy in documentation. When multiple code sections use the same functions or variables, it can be tempting to copy and paste documentation, resulting in redundant documentation and confusing code.” However, these challenges can be overcome with enough diligence. “To overcome these challenges, it is essential to establish specific standards for documentation management and to incorporate documentation review processes into the development workflow.” As long as these standards can be maintained and code documentation is regularly reviewed, the documentation implemented with your projects should be of high quality and make understanding your projects much easier for your fellow developers.

Article: https://www.skillreactor.io/blog/the-importance-of-code-documentation-and-how-to-do-it-right/

From the blog CS@Worcester – P. McManus Worcester State CS Blog by patrickmcmanus1 and used with permission of the author. All other rights reserved by the author.

The article I chose for this week’s blog post is “What Is an Anti-Pattern?” by Andreas Schöngruber. I chose this article because it discusses what anti-patterns are, gives some examples of anti-patterns, and how to avoid them. I chose this article for this week’s blog because it fits well with the syllabus topic of anti-patterns. I found the section about recognizing and avoiding anti-patterns to be very helpful. This blog post will focus on the aforementioned section about recognizing and avoiding anti-patterns in your code.

I will first discuss the section of the article which discusses recognizing anti-patterns in your code. One method that the article mentions involves keeping an open mind and looking to others for feedback. “When identifying anti-patterns in our code or design, we must keep an open mind and question our assumptions. Sometimes, we may become attached to a solution that required a lot of time and effort, but there might be a better solution out there. To avoid this, it is helpful to seek feedback from others.” As this quote states, it is imperative not to be too attached to a process that you developed or are developing, especially if the time it takes to develop or implement this feature is more than the value that the feature is worth. Another important part of being able to mitigate the harm done by anti-patterns is knowing how to avoid them.

While being able to identify anti-patterns is incredibly important, it is also important that one knows how to prevent their occurrence in the first place. One method of doing so is by stepping back and looking at the greater picture of the project that you are working on. “When working on software projects, it is essential to be aware of common pitfalls that can lead to anti-patterns. One strategy to avoid these pitfalls is to take a step back and consider the larger context of the problem. Understanding the problem in its entirety will help in coming up with a good solution.” Instead of being hyper-focused on one part of a larger project, which could lead to anti-patterns arising in your code, its best to take a step back occasionally to make sure what you are working on is not falling into the traps of anti-patterns. Another method of preventing anti-patterns would be a divide-and-conquer approach to developing features. “Another strategy is to break down large problems into smaller pieces. Doing this can help avoid getting overwhelmed and make it easier to spot issues and inefficiencies.” Using this strategy can be very beneficial because it can allow you to see anti-patterns as they appear in your code.

Article: https://www.baeldung.com/cs/anti-patterns

From the blog CS@Worcester – P. McManus Worcester State CS Blog by patrickmcmanus1 and used with permission of the author. All other rights reserved by the author.

Through the duration of this class, we have worked a lot with different types of classes, abstract and concrete, as well as interfaces to better design the code. It was not a new concept to me, as I have learned some of the basics to these in prior classes. However, I never truly understood the benefits and the right time to incorporate each. The articles I found give a simple explanation on the distinctions between concrete classes, abstract classes, and interfaces, as well as the correct situations to use them in.

A concrete class, sometimes just referred to as a class, is used to specify any entity. It also can work as a blueprint for all entities with the same attributes. An abstract class and interfaces are similar and was often confusing for me to distinguish the two of them at first. An abstract class will have methods implemented inside the body, but abstract methods will not have the body of the method inside this class. For example, the duck class I was working with for Homework 2 has the abstract class Duck and the abstract method display(). The body of the method is not present in the abstract class because the different concrete classes implementing Duck uses display() to show different messages. An interface only has the method names included for classes to implement with the interface but does not have any body of the methods. This is what partially distinguishes abstract classes from interfaces, as abstract classes can have concrete methods defined in them while interfaces can only have the method names defined. Interfaces are handy when only needing to enforce a contract. Whoever implements this interface will provide an implementation of all the methods. Abstract classes are helpful when only needing partial implementation, which leaves the responsibility of implementing non-useful methods from the class.

The phrase “program to an interface, not an implementation” is new to me and I am starting to make more sense of it. Concrete classes are the actual implementation, interfaces are the contract, and abstract classes are a trade-off between both. Being able to fully program these three structures into the program helps with maintainability, extensibility, and testability. When programming to an interface, you are forced to split the program into subsystems, with each subsystem responsible for certain tasks and having the ability to communicate with each other to complete the whole task. The key to making the program more flexible is focusing the design on what the code is doing rather than how it does it.

I decided to pick this topic for my blog because I had always had a good idea of how to physically write programs to function correctly. However, something that I never focused on before was the structure of the code which can help when needing to develop the program further after initial creation. Most of our time spent in the class so far has been focusing on this concept and it is proving to be very important the more a program continues to develop.

Program to Interface, Not Implementation – Beginner’s Tutorial for Understanding Interface, Abstract Class and Concrete Class – CodeProject

Programming to an Interface – DZone

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.

In the exciting realm of web development, the successful implementation of web systems hinges on understanding the intricate dance between three core components: the front end, the back end, and the data persistence layer. This blog post aims to dissect these vital components, shedding light on how they collaborate harmoniously to bring web applications to life.

The Front-End Canvas

Imagine the front end as the artist’s canvas, the visual facade of your web application that users interact with directly. It encompasses everything you see and interact with on a website—buttons, forms, navigation menus, and the overall layout. The front end relies on a trio of essential technologies:

1. HTML (Hypertext Markup Language): HTML acts as the foundation, structuring web pages by defining content and layout.
2. CSS (Cascading Style Sheets): CSS is the stylistic wizard responsible for the visual appeal, ensuring that the web elements harmonize seamlessly.
3. JavaScript: JavaScript adds interactivity to the canvas, bringing it to life by creating dynamic elements, managing user input, and facilitating communication with the back end.

The Back-End Engine

Behind the scenes, the back end serves as the powerhouse of your web application. It handles user requests, processes data, interacts with databases, and sends responses. Several technologies and frameworks excel in back-end development:

1. Node.js: Node.js enables JavaScript to run on the server side, making full-stack development a breeze.
2. Ruby on Rails: Rails offers a structured framework that simplifies the creation of robust web applications with concise code.

The Data Persistence Layer

No web system is complete without a reliable data persistence layer. This layer manages data storage, retrieval, and efficient data management. It’s home to various types of databases, including:

1. MySQL: MySQL, a popular relational database, is known for its reliability and is widely used in web applications.

The Synchronized Symphony

These three layers—front end, back end, and data persistence—complement each other to deliver a seamless user experience. When a user interacts with the front end, JavaScript often sends HTTP requests to the back end. The back end processes these requests, interacts with the chosen database to retrieve or store data, and then sends a response back to the front end. JavaScript on the front end dynamically updates the user interface based on this response, creating a responsive and interactive web application.

In Closing

Understanding the synergy between the front end, back end, and data persistence layer is fundamental to web development. These layers work in harmony, much like the instruments in an orchestra, to create the symphony of a fully functional web system. As you embark on your web development journey, remember that mastery of these layers takes time, practice, and a touch of artistry. So, keep coding, keep building, and explore the boundless possibilities of web system implementation.

References:

• MDN Web Docs – HTML, CSS, and JavaScript
• MySQL Documentation

From the blog CS-343 – Hieu Tran Blog by Trung Hiếu and used with permission of the author. All other rights reserved by the author.

https://refactoring.guru/design-patterns/singleton

This week, I wanted to a find a source relating to software design and architectures. I’ve been curious about what I would need to know so I could write more robust and efficient code. One aspect of improving my code would be knowing how best to preserve available system memory and perform whatever tasks I need to within as few CPU cycles as I can. If my program is creating multiple instances of a class that are all doing the same thing, my code would be consuming more system resources than if I had one instance of a class that could be accessed by other parts of my code. The Singleton design pattern seeks to preserve memory consumption by utilizing a single static instance of a class that may be globally referenced from the rest of the program. To properly implement the Singleton, the constructor for your Singleton instance should be static and private. To get the instance, you would also need a public static creation method.

My homework for this week involves refactoring a class into the Singleton pattern, so I was especially interested in learning about it. I found this blog called The Refactoring Guru, and a post explaining the implementation of the Singleton, as well as the pros and cons from a design perspective. The Singleton design is useful when a program needs global access to a class, like when a program has a single attached database. The drawbacks of the Singleton approach, though, are that it does too many things at once in violation of the Single Responsibility Principle, and that it may compromise your program’s security because of a crucial class being accessed as a global variable.

The final paragraph of the blog post makes some comparisons between the Singleton design and two other software design patterns, Façade and Flyweight. Façade is a design pattern of constructing a simple user interface with a complicated backend. This design pattern offers a sort of “black box” functionality to users, having a simple frontend to interact with without the need to inform users about the inner implementations of the software. The practical example given for a Façade software design is a video encoding service that accepts video files from the user as input and returns the same file encoded in a new file format. The user would only need to interact with the function that accepts a file and a desired file type as parameters, without needing to access the methods within the program that perform operations on the input file.

This blog includes helpful illustrations and pseudocode to explain multiple different software design patterns. I’ve been needing more resources on broader software structure and design rather than individual blocks of code, and I’m happy that I found this website.

From the blog CS@Worcester – Michael's Programming Blog by mikesprogrammingblog and used with permission of the author. All other rights reserved by the author.

For the entirety of this course so far we have been working and getting familiar with the version control tool git. In this week’s blog I will be writing about a blog called “What is Git | Explore a Distributed Version Control Tool” by Reshma Ahmed. I have chosen this article in particular to see how it came to existence, the roles they play in companies, and to get a further understanding in addition to what we have learned in class.

From the article I have learned the different types of version control such as centralized version control system and distributed version control systems. Git was created in 2005 by Linus Torvalds designed to “handle small to large projects with efficiency”. Git is a distributive version control system which is a system that prevents corruption and crashes that were caused from having a server hosted in a single repository such as in centralized version control systems due to everyone having a copy on their machine of their local repository. When reflecting back to the course we have been practicing with pushing and pulling from repositories, branches, as well as removing and adding commits. The GitKit activities worked on in class shown us practical issues that one may face with git such as merging issues as well as issues involving different versions of commits.

The article describes some of the features of git which we have looked at in class such as being open source as well as being secure. Open source software encourages transparency, collaboration, and accessibility similar to the FOSS communities mentioned in the first GitKit activity done in class. The article reads “Git uses the SHA1 to name and identify objects within its repository”. This concept becomes apparent from seeing in the GitKit activities done in class when applying commands such as “git log” that shows a commits’ hash as well as the date a commit was made.

Git not only is used in the software development community but plays a detrimental role in companies with more and more companies using git as their go-to version control system. Some of these companies include tech giants such as “Facebook, Yahoo, Twitter, eBay, Salesforce, [and] Microsoft” which shows the significance of git.

When reflecting for my personal future use of git, practical applications of git in the field of machine learning and data science is using git to manage datasets to ensure reproducibility as well as data integrity. In addition, I plan on using git for my data mining course project when collaborating with other peers.

Links

https://www.edureka.co/blog/what-is-git/#companies_using_git

From the blog CS@Worcester – Anthony Duong CS Blog by anthony duong and used with permission of the author. All other rights reserved by the author.

From the blog CS@Worcester – Kyler's Blog by kylerlai and used with permission of the author. All other rights reserved by the author.

When it comes to writing code, the one thing you want to keep an eye on is that you’re not using the same line of code you used on multiple projects. The don’t repeat yourself principle also known as the DRY principle aims to solve problems is knowledge of duplication. This idea is applied through all levels and phases of software development, most of the time it’s used while making classes. When making classes you end up implementing the same logic in multiple parts of the code. A solution is to remove the common functionality and only implement the parts that are different.

Another example of repeating yourself happens while you’re storing data. You start to create unnecessary attributes in your table, usually, you can derive those attributes from other attributes since they’re mutually dependent on each other. The problem with duplication is that things can change and once you make one change you have to change all of its representations. Making changes requires analysis, In other words not making any proper changes will lead to opposite representations of the same knowledge. These duplicates can happen in multiple ways someone could make a mistake while making the design, and a strict deadline can make people feel rushed to meet that deadline.

DRY is a principle and there are three methods to implement that principle. First is abstractions which are commonly used when making classes, when multiple classes are shared and come with common logic you simply want to abstract the logic into a superclass that each class inherits. The standard object-oriented program has a lot of practices that encourage the DRY principle for writing reusable, readable, and maintainable code. Second automation is a project case for developers. It’s to make sure that developers are communicating with each other so they don’t repeat finished work and talk about any problems they’re having. Last is normalization, this case is for designing databases. Repetition is common in a lot of data representation but creates redundant data, which is hard to maintain. You would want to extract the cases into a separate entity then the source references that entity. The goal is to ensure that the data is consistent and distributed correctly. Data normalization removes repetition in data, making the database more flexible. 

The reason why I picked this topic is because I tend to repeat myself a lot thinking that it wouldn’t be too much of a problem for me to end up having problems with my code and making my code a little more confusing. By using this principle and using the three methods it helps me make sure that my code is readable, reusable, and easy to maintain. I feel like this principle is important to use for everybody who is making a code by themselves or as a group.

Sources: https://www.plutora.com/blog/understanding-the-dry-dont-repeat-yourself-principle

From the blog CS@Worcester – Kaylene Noel's Blog by Kaylene Noel and used with permission of the author. All other rights reserved by the author.