Tommorow, Not Today

As with many classes, topics, and projects I have been a part of for the last few years, I see a consistent pattern. The unwavering focus on what’s going on in the present and never connecting the dots on how something might benefit me in the future.

Code documentation is just one of the many examples I could come up with to further my point. Up until now, all my work has followed the motto of “me, myself, and I,” failing to see that in the future that won’t be the case. Eventually, everyone will find themselves a part of a team, and there is nothing worse than an amateur teammate. Let’s take a deeper look into code documentation and why it will eventually be an asset to not just you but also your future teammates.

Type of Code Documentation

Internal Code Documentation: Intended for developers inside the organization.

• Process Documentation: Provides high-level information like product requirements, roadmaps, notes, and reports.
• Developer Documentation: Provides detailed instructions for developers and staff for building, testing, deploying, or maintaining the software.

External Code Documentation: Intended for developers outside the organization who integrate with the product or need to understand its code.

• External Developer Documentation: Provides essential instructions for using source code, integrating with a product, and leveraging developer interfaces like APIs and CLIs.
• Enterprise Documentation: Furnishes information for IT staff involved in software deployment, covering hardware requirements, sizing, operational needs, and maintenance guidelines.
• Usage Documentation: Guides non-developer users on product utilization without relying on programmatic interfaces. Describes main functionalities within the product’s UI.
• Just-in-Time Documentation: Supports developers as needed, often in the form of knowledge base articles, FAQ pages, or blog posts, added in response to new features or requirements.

Low-Level or Inline Documentation: Resides within the source code and explains details of specific code parts in isolation, such as the purpose of certain functions and arguments.

High-Level Documentation: Describes the architecture, design principles, implementation guidelines, or other broader concerns.

Walkthrough Documentation: Describes flows, patterns, and other important parts of the codebase, especially for developers who need to contribute to the code.

Food for Thought

Documentation might seem straightforward, but there are some issues that must be considered whenever starting a new document.

• Knowing Your Audience: Depending on why/who you are writing your documentation for, you must consider their level of understanding when it comes to your subject.
• Updating Documentation: It is very easy to push changes to your software and forget to also push changes to documentation. This starts a cycle with co-workers where the documentation falls behind and becomes uncomprehensible.

Tommorow

Embracing comprehensive code documentation is not just a practice for today but an investment in our collective future. As we transition from individual contributors to collaborative team members, the value of clear, well-maintained documentation becomes vital to future projects.

Source – https://swimm.io/learn/code-documentation/code-documentation-benefits-challenges-and-tips-for-success

From the blog CS@Worcester – CS: Start to Finish by mrjfatal and used with permission of the author. All other rights reserved by the author.

We’ve gone over a couple of design patterns in class this semester. Some that come to mind are the singleton and factory patterns, both of the creational variety. This latter half has been more focused on practical applications of software construction, taking a look into the Thea’s Pantry system that uses a microservices approach, but earlier on we were working with design decisionmaking and approaches.

A software desing pattern is a reusable solution to a problem that occurs often. The three main types of design patterns are creational, structural and behavioral. This is all well and good, but what do these types entail? I found this blog post from NetSolutions regarding the subject, and it gives a brief explanation of each as well as some examples.

Creational design patterns are solutions for the creation of objects and how they are used. The aforementioned singleton and factory patterns are creational because they dictate the way that objects are meant to be created based on the circumstances surrounding it. Singleton ensures a single instance of an object that can be called, while the factory is a sort of constructor of objects that utilizes an interface to form an object from sub-classes.

Structural design patterns relate to object composition to form better flexibility when working on a large-scale project. For example, an adpater is a structural design pattern that allows for incompatible interfaces to work together, creating greater flexibility in the program. The facade pattern is a sort of application of encapsulation and abstraction, allowing for the hiding of complexity with an interface, making it easier to work with.

Behavioral design patterns deal with separate objects and the way they share responsibility and communicate. The strategy design pattern is an example of this, where algorithms are put into a family where each algorithm is only called when it needs to be called, increasing efficiency. The observer pattern links one object to many dependents, notifying the observer object whenever any depedent has experienced any event.

It seems important to have these tools in your belt, considering that many of the problems that these design patterns solve occur fairly regularly even when developing different pieces of software. The one thing I would consider being wary of is using software design patterns at all times when you may not need it. For example, the factory pattern is best used when working on a fairly large project, but is not necessary at a smaller scale. Of course, when a project goes from small to large, a refactor may be called for, but perhaps the factory pattern is not the best tool for the job, it’s instead a builder or prototype. There is no one-size-fits-all solution, and so it’s also a skill to know when and how to use patterns and not just apply them randomly.

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

Anti-Patterns

Anti-Patterns are “imperfect” fixes that may seem like they solve a problem, but over time, can lead to more problems where using anti-patterns are more inconvenient than not. Because anti-patterns cause problems over time, teams are forced to go back and fix them which lead to higher costs and delayed release schedule.

Types of Anti-Patterns

Spaghetti Code

Spaghetti code refers to the logical structure of the code resembling a plate of spaghetti, meaning it is unorganized and confusing. Spaghetti code usually occurs when a developer starts a project without putting much thought into the organization of the code. Although the end product may work, adding functionality may increase fragility. Using the spaghetti analogy, adding more code would be like adding more spaghetti leading to an even larger tangled mess.

Golden Hammer

Golden Hammer refers to one tool being the solution to all problems. A developer may have used a well designed piece of code to solve previous problems, but relies too heavily on it by trying to use the code for problems that do not necessarily belong. Forcing code where it may not belong can lead to spaghetti code. The Golden Hammer concept can be thought of as trying to cut a piece of wood with a hammer.

Boat Anchor

The Boat Anchor anti-pattern occurs when a piece of code is left in the code base, so it can be saved for later use. Although the code may not make sense for the program, the thought process of saving the code is if the code is needed later it can be turned on and off with comments. Some may think because a piece of code is commented out, there is no harm in leaving it. However leaving unnecessary code can lead other developers confused about what the code is intended for and over time may slow down build times. Turning the code back on may also break the code if changes were made to the point where the saved code may no longer be compatible.

God Object

A God Object is an object or a class that has too much responsibility for the program. This violates the single responsibility principle, as every object and class should only be responsible for one single part of the program. For example, there is a customer ID class responsible for the customer’s first and last name, transactions, and more. Rather than the customer ID class manage all those details, better practice would be to have customer ID be responsible for the customer’s name while a separate class is created for transactions.

Reflection

This resource was chosen because it explains what anti-patterns are, why they are bad, and listed common types of anti patterns. The article was informative as I realized I am guilty of utilizing many of these anti patterns such as spaghetti code and god object. After reading this article I am now aware of these anti patterns, and will be more mindful to not use them in the future.

Resources:

https://www.lucidchart.com/blog/what-are-software-anti-patterns

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

The Roots of Today’s Modern Backend Engineering Practices: https://blog.pragmaticengineer.com/the-roots-of-modern-backend-engineering-practices/

Summary:
In this blog post, we explore the evolution of modern backend practices through the lens of Joshua Burgin, an industry veteran with a rich background in backend development. The journey begins with his early days at Amazon, where accidental outages led to valuable lessons in observability and robust systems. We then travel back to 1969, witnessing the birth of ARPANET, a pioneering project that laid the groundwork for today’s distributed networks. The narrative continues into the 1980s, marking the rise of the internet and web-based computing, crucial milestones that shaped the challenges and solutions of backend development.

Reason for Selection:
This resource was chosen for its deep exploration of the historical roots of modern backend engineering practices. Joshua Burgin’s firsthand experiences, coupled with insights into the development of ARPANET and the internet, provide a holistic view of the challenges, innovations, and pivotal moments that have shaped the backend landscape.

Comments on Content:
Joshua’s recounting of the early days at Amazon offers a vivid picture of the challenges faced by developers in the late ’90s. The simplicity of tools like shell scripting and Perl, coupled with the manual deployment processes, highlights the stark contrast to today’s sophisticated backend practices. The emphasis on observability and the significance of monitoring, learned through real-world incidents, resonates with the importance of these aspects in contemporary development.

The exploration of ARPANET’s birth showcases the pioneering spirit of the engineers who laid the foundation for distributed networks. The introduction of packet switching and its impact on fault tolerance and high availability provides valuable context for current backend practices. Understanding these early challenges fosters an appreciation for the sophisticated tools available today.

As the narrative transitions to the internet’s rise in the 1980s, the challenges faced by businesses like Amazon in scaling infrastructure and serving international audiences become apparent. The change from text-based interfaces to graphical browsers reflects the transformative power of user-friendly technologies, a lesson relevant in today’s user-centric development approaches.

Personal Reflection:
This resource has deepened my understanding of the roots of backend engineering, emphasizing the iterative nature of progress in technology. The anecdotes from Joshua’s career underscore the importance of learning from failures and adapting to the evolving landscape. The historical context provided by ARPANET and the internet’s emergence serves as a reminder of the continuous innovation that defines backend development.

Moving forward, I plan to apply the lessons on observability and robust system design in my own projects. The historical insights have reinforced the idea that every complex system today stands on the lessons from earlier times, encouraging a forward-looking approach that considers the evolution of technology.

From the blog CS@Worcester – Site Title by rkaranja1002 and used with permission of the author. All other rights reserved by the author.

Inversion of control is a software principle that asserts a program can benefit in terms of testability and usability if the management of an application’s flow is transferred to a different part of the program. I.O.C’s framework takes the management of an application’s implementation away from the developer. When there are interactions that require custom business logic, the I.O.C framework will use the code provided by the developer. This is the “inversion” point of the inversion of control design principle. The most common application for Inversion of control is Java servers faces. I.O.C frameworks implement low-level and problem-prone activities, it allows the developer to focus on custom business logic instead of tedious tasks.  The one thing about inversion of control is that it can confuse what qualifies as an I.O.C and what doesn’t. Some examples of inversion of control are the use of event-based user interfaces, the use of shared cache, and the use of comprehension framework. The range of development changes that qualify as I.O.C contributes to the term. I.O.C is a principle, not a design pattern- the implementation depends on the developer. I.O.C just provides high-level guidelines. Inversion of control and dependency injection are usually used interchangeably. Dependency injection is one implementation of I.O.C., it’s a technique that allows objects to be separated from other objects that they depend on.

Dependency injection suggests that instead of making an instance of class b into class a using the new operation, the object of class b should be placed into class a using one of these methods constructor injection, setter injection, and interface injection. Another example of implementation in I.O.C is the spring framework. That contains instances and manages the lifecycle of the objects in the program. The user in the configuration file provides information that relates to what objects and dependencies are used by the application like Java code. The benefits of Inversion of control are that it makes the application easier to test and maintain, reduces the amount of application code, and also decreases the coupling between classes.

https://www.theserverside.com/definition/inversion-of-control-IoC

https://www.educative.io/answers/what-is-inversion-of-control

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.

What is documentation in computer science? So, documentation in computer science is the information that helps describe the product to the people who deploy, develop, and use it. This includes technical manuals and online materials, documentation sometimes refers to source information about the product discussed in code comments, design documentation, and session notes. Documentation is a way for programmers to describe their products and the process they use to create them in formal writing. Usually with early programmers, they would use notes and comments, but as programming got more complicated technical writers took over the documentation process. Documentation shows what software developers did when making the software and what users and IT staff must do when deploying and using it. Documentation is usually included in the software user interface as comments and helps the process of documentation. The information is usually divided into categories that include Evaluating, planning, using, maintaining, and installing.

So why is documentation so important? The reason why it’s important is because it provides information about a software program for everyone involved in the process of making it, developing it, and using it. Documentation records the development process and assists in basic tasks like troubleshooting and installation. With good documentation, it helps get the users familiar with the software and its features. Documentation can have a significant role in driving user acceptance. It also can reduce the burden of support teams, because it gives users the power to troubleshoot issues. Software documentation can be a living document that is updated over the software development life. The use and communication of documentation encourage users to provide developers with information on problems users have with the software and what other features they need. Developers can respond with software updates, improving their customer satisfaction and the user’s experience. 

There are two types of software documentation, internal and external. Internal documentation is used inside the company, it usually includes administrative documentation and developer documentation. Administrative documentation is a high-level administrative guideline, roadmaps, and product requirements for the software development team and project managers. Development documentation provides instructions to developers for building the software and guides them through the development process. It needs the required documents, which describe how the software should perform when tested. External software documentation helps provide IT managers and end users with information on how to deploy and use the software, It usually includes end-user documentation, enterprise user documentation, and just-in-time documentation. End-user documentation gives users basic instructions on how to use, install, and troubleshoot the software. Enterprise documentation usually has documentation for IT staff who deploy the software across the enterprise. Just-in-time documentation provides end users with support documentation at the exact time they will need it. Documentation is important because it helps keep track of all the work that was done with the software and gets updated when any changes are made. It helps developers and users get to know the software better and have a clear understanding of the code.

https://www.geeksforgeeks.org/overview-software-documentation/

https://www.techtarget.com/searchsoftwarequality/definition/documentation#:~:text=In%20the%20software%20development%20process,of%20manuals%20and%20help%20capabilities.

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.

For this week, I wanted to talk about the creation of comic books, and how it relates to Software Process Management and Software Design. Within the article linked below, it describes the process of how a comic is created, and the steps needed to reach a final project. I specifically wanted to look more into this as the process is quite similar to how software is developed.

The second step is writing a plot, which is much like creating a backlog for your process, planning the beginning, middle and end of the process.

Then, its off to creating the art, which is a multi-step process, which is much like creating the code. For the artists, they need to sketch, then line, then ink and even maybe color the panels of the comic, which parallels how code will need a framework, then main code, supplemental code, and comments to build on top of each other. This process isn’t always in a predetermined order, and can vary from project to project.

And then theres editing and review. Everyone looks over the draft of the work they’ve made, and then tweaks whatever needs adjustments as needed. This process might lead to the recreation of art or code, depending on which process we’re discussing. Once a review gets a pass, they’re ready to finalize and move onto the last step, which is…

Publishing and marketing! Once you’re done, you send the finished copy of the work to consumers to receive, and perhaps you’ll even advertise it, if its not well-known. This can include things like advertisements, sponsorships, and even word of mouth.

The parallels of the dynamics in which these processes interest me a ton as someone whos also minoring in art, and wants to go into a digital design or digital-art focused field, whether it be game design or webcomics. It’s kinda awesome to see that theres a sort of venn diagram between my two passions, and that they can intersect.

EDIT: I meant to post this earlier before, but I had connectivity issues and it never posted when I thought it did. I only realized because a friend wanted to read my blog, haha. To clarify, this blog is intended for Week-12, and for both classes, not 13, it just was posted late due to issues. My apologies for this inconvenience.

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.

Now I know what everyone is thinking, ‘You lied in your last blog.’ Yes, I did, and guess what? This is my blog, so that’s okay. You see, I could not pass up on this beautiful opportunity to kill two birds with one stone. As you may remember from my last blog, I complained about how hard it was to come up with topic ideas for CS-343. Well, well, if by some miracle I read that if topics intertwine between your two classes (343/348), we could count one blog for both classes (shoutout Prof Wurst :)).

Enough yapping, clean code time. I believe it was only a year ago when I first started taking coding seriously, and I can recall how awful my code looked. It worked… but if you wanted to debug, you had to pray before opening it. We are talking about one-function programs, with no formatting and variable names that would drive any professor mad. I quickly realized how important clean code was after watching some YouTube videos and seeing how much easier debugging was if your code had a good flow and was properly formatted. This is where I stopped when it came to clean code, unknowing that there were 100+ other factors that all combine to make clean code.

While exploring LinkedIn, I came across this article by Oleabhiele Donald titled ‘Benefits of Clean Code In Your Application Development.’ I gave this a full read and was really surprised about all the little ways I could make my code even better than it already was. Now I 1000% recommend giving it a full read, but I’m going to talk about some of the techniques that were mentioned that I didn’t know at the time or found most beneficial to me.

Use comments sparingly:

• Limit the use of comments to when necessary, ensuring clarity and conciseness. Overusing comments can clutter the code, making it harder to read. Aim for clear and concise comments that add value.

Write small, focused methods:

• Break down larger methods into smaller, focused ones, each with a single responsibility. This approach improves code understanding and facilitates easier modification.

Use unit testing:

• Incorporate unit testing practices to verify code functionality and prevent the introduction of errors. Well-designed unit tests contribute to clean and reliable code.

Avoid duplication:

• Identify and eliminate code duplication by utilizing methods, classes, and inheritance. Reducing duplication enhances code maintainability and modifiability.

These techniques stood out to me mostly because they were things I just didn’t think about. I love to keep a list on my desktop notepad that always reminds me of some of the key steps to clean code.

Why Clean Code? This a very simple answer thanks to the article, clean code is important enhances readability, making it easier for developers to understand, maintain, and collaborate on software projects. It also improves efficiency, scalability, and reduces the likelihood of introducing bugs, ultimately leading to more reliable software and a happier programmer.

Source: https://www.linkedin.com/pulse/benefits-clean-code-your-application-development-daniel-donald/

From the blog CS@Worcester – CS: Start to Finish by mrjfatal and used with permission of the author. All other rights reserved by the author.