Blog 3 – Understand clean code

Coding is just like writing an essay, it requires a logical structure, clear message, and readability so others can understand it. That’s why we need “Clean Code” in every project of programming. Clean code refers to code that’s easy to read, understand, and maintain. The ultimate goal is not just working software, but software that remains clean and maintainable throughout its lifecycle. So, how do we write clean code?

According to the Codacy article “What Is Clean Code? A Guide to Principles and Best Practices” (https://blog.codacy.com/what-is-clean-code). They provide a good explanation about clean code and how do we make the code become more understandable for others to read, and also help us to improve more in coding skill.

Why Clean Code Matters

  • Readability & Maintenance: Clear code helps developers (including new ones) understand and navigate the codebase faster. blog.codacy.com
  • Team Collaboration: When code follows shared, clean practices, it’s easier for team members to read each other’s work and contribute. blog.codacy.com
  • Debugging: Clean structure (good names, simple functions) makes it easier to isolate and fix bugs. blog.codacy.com
  • Reliability: By adhering to best practices, you reduce the chances of introducing bugs and make the code more stable and reliable. blog.codacy.com

Key Principles & Best Practices

The article outlines several principles that help make code clean:

  1. Avoid Hard-Coded Numbers
    • Use named constants instead of “magic” numbers so their meaning is clear and changeable.
  2. Use Meaningful Names
    • Choose variable, function, and class names that reveal their intent and purpose. blog.codacy.com
    • If a name needs a comment to explain it, the name itself is probably too vague.
  3. Use Comments Wisely
    • Don’t comment the obvious. Instead, use comments to explain why something is done, not what.
  4. Write Short, Single-Purpose Functions
    • Functions should do one thing (following the Single Responsibility Principle).
    • When functions become long or handle multiple tasks, break them into smaller ones.
  5. Apply the DRY Principle (“Don’t Repeat Yourself”)
    • Avoid duplicating logic; reuse code via functions, modules, or abstractions.
  6. Follow Code-Writing Standards
    • Use consistent formatting, naming conventions, and style according to your language’s community or team guidelines. blog.codacy.com
    • Examples include PEP 8 for Python or common JavaScript/Java style guides.
  7. Encapsulate Nested Conditionals
    • Instead of deeply nested if/else logic, move conditional logic into well-named helper functions — improves readability and reusability.
  8. Refactor Continuously
    • Regularly revisit and clean up your code. Leave it in a better state than when you found it.
  9. Use Version Control
    • Track your changes using a version control system (like Git). It helps with collaboration, rolling back changes, and safer refactoring.

Automate Clean Code Practices

  • Codacy recommends using its tools (static code analysis, duplication detection, code metrics) to automate enforcement of clean-code rules as you write.
  • This helps catch code-quality issues and security vulnerabilities early, keeping the codebase maintainable and high-quality. blog.codacy.com

Mindset Over Rules

  • Clean code is more than following a checklist — it’s a mindset and a commitment to quality.
  • The article argues for writing code not just to work, but to be read and maintained by humans.

From the blog CS@Worcester – Nguyen Technique by Nguyen Vuong and used with permission of the author. All other rights reserved by the author.

CS-348 Quarter 3 Blog Post

For Quarter 3 I’ve chosen this article written by Ting Yu from the The Brink, at Boston University.
https://www.bu.edu/articles/2022/how-copyrights-patents-trademarks-may-stifle-creativity-and-progress/

This article was written in August of 2022. It establishes and idea that law has not been able to keep up with the development of the digital era. This idea, proposed by Jessica Silbey, an expert on constitutional and intellectual property law argues that current law does nothing to advance the public’s creativity and ability to make society better for the collective, instead society lined up today to empower individuals and corporations. In other words, Silbey explains that the idea of individual copyright and trademarking of ones own work is more an empowerment to exclude, making copyright and trademark law seem more on the offensive than defensive.

The reason I decided that this article fit the bill for the semester is of course its relevance to our topics surrounding copyright law and trademarks of our work as programmers and developers. But at the same time I chose it for its interesting take on the implications of copyright law and trademarks on the creativity of the public.

Pulling down from the summary of the article about the empowerment to exclude being used to describe copyright and trademarks, at first it felt like a weird take but the more I thought about it the more it made sense to me. While at face value the idea of copyright and trademarks is to protect the intellectual property of whoever created said property, on the grand scheme of things, especially in a world where you can instantly contact someone from the other side of the planet in an instant it does feel more like a trademark plays the role of a bouncer at the entrance of a club, letting in select people and excluding others. Although the people not being the problem but the intentions of said people as trademarks and copyright determine what one can do with an intellectual property. Something specific that Silbey brings up that to me shows the severe issue with current law is the example about how in days long past, it was usually the inventor of something who would own the patent to said thing, but in todays world its teams of people working all towards a single goal, usually in competition with other companies. Leaving copyright and trademarks usually in the hands of the company the team is operating under depending on contract stipulations. For example the battle between Microsoft, Sony and Nintendo to be the next big innovator in the gaming industry creates hostile work environments powered by profit and quotas. Copyright and trademarks usually held tight with an iron fist by these companies. So while I do need to give this idea more thought I definitely think Silbey has a strong point that shes making for us.

From the blog CS@Worcester – Splaine CS Blog by Brady Splaine and used with permission of the author. All other rights reserved by the author.

CS343: The Lost Art of Refactoring

Papa Bear, is it true the humans put their noodles in one bowl, their vegetables in another, and the broth in a third, unrelated one?

This week I read a blog article from Martin Fowler’s blog titled “Refactoring: This Class is Too Large” by Clare Sudbury. Find that post here.

What was the blog about?

Sudbury walks us through how she would refactor a poorly-written (real-life example) codebase and the common mistakes people make when developing code that ultimately precipitate rounds of refactoring.

Why do we refactor?

Our code evolves. At first, as Sudbury puts it, what most people have are big “entrance halls” to their problems; big main methods and such where a jumble of not-necessarily related but nevertheless heavily coupled code sits together for the sake of convenience and because we have, at that point, only a shaky or infirm grasp of what architecture our code will have in the future. That’s fine–for a start, and for a time.

Problems arise when we keep trying to entertain in the “entrance hall”. We need to refactor in order for our structural conventions to even continue to make sense.

Why did I choose this article?

I need to be better and more strategic more about refactoring, and having a ton of visual references (the examples) paired with the reinforcements of best practices helps tremendously.

There are also other considerations we haven’t talked about in-class that Sudbury talks about in more detail, such as how to structure our refactors within a series of commits that make logical sense for anyone looking from the outside in, so her blog is doubly worth reading for those extra touches alone.

What are the steps to refactoring?

For the most part, these steps are well-founded in the context of our course and should be pretty easily understood in that sense. In short, though, we can think of refactoring out a method from a parent class as having six distinct steps.

  1. Organize methods and related code into distinct regions–more of a logistical than an architectural point, but keeps with what we’ve learned in this course. Code that changes together stays (and collapses) together.
  2. Verify dependencies and class relationships of the method to be refactored using diagrams or similar tools–again, tracks with what we’ve learned. This is exactly the use case of UML class and sequence diagrams.
  3. Clean-up methods that stay in the “entrance hall”–we’ll keep some parts of our method in our main class, but with appropriate changes, since methods that they might have invoked may now be sitting elsewhere.
  4. Create a new class to contain the refactored method and test it in the simplest terms possible (tiny steps principle).
  5. Build more test coverage for the new class (TDD).
  6. Move method(s) to the new class.

We repeat for as many methods with unique behaviors as there are in the code.

How does this relate to the course material?

We learned that, in the course of developing a problem, we might have code structures that become obsolesced or which are consolidated into others, i.e. composition. And we’ve done refactoring a little, as with the DuckSimulator code from one of our homeworks. But what we haven’t looked at is how to actually systemize this process of refactoring so that it becomes second-nature to us and the steps taken become intuitive rather than a feat of mental gymnastics. If we can’t conceptualize the process of refactoring as an organic evolution of our codebase, we are doomed to stay in cycles of bad code and refactoring, bad code and refactoring, etc. For my own sake and for that of my professional career, I’d better learn to refactor more.

It’s not just about making unit tests.

Kevin N.

From the blog CS@Worcester – Kevin D. Nguyen by Kevin Nguyen and used with permission of the author. All other rights reserved by the author.

Week 3-CS 343 blog: REST API DEVELOPMENTS AND BEST PRACTICES

Rest API is something that really interesting and fun to work with. It enables communication between different software systems over the internet, typically using HTTP protocol. However, Rest API can be difficult sometimes due to its complex queries and filtering, and also batch operations and side effects, etc…Good thing is I went through this blog written by “Medium”. They explained some of the good tips for us to practice with REST API calls. I will walk through their ideas and plans to help us be better at REST API.

Here is their blog https://medium.com/epignosis-engineering/rest-api-development-tips-and-best-practices-part-1-9cbd4b924285

  1. Planning
    • Do research first: Study existing REST API designs, standards, and popular APIs. Consider whether REST is the right paradigm, but also explore alternatives like GraphQL.
    • Look at other APIs: Try working with well-known APIs (GitHub, Stripe, Twitter, Paypal) to understand what work and what doesn’t

2. Foundations Matter

  • A solid early foundation avoids costly refactors later.
  • Assume the API will grow: design for scale, future endpoints, versioning, pagination, analytics, etc.

3. Specification

  • Write an API spec before coding
  • Use tools like OpenAPI/Swagger for designing your API contract
  • Specification pays off – especially for APs that are not just internal

4. Testing

  • Critical for APIs: because they connect server data with clients, they need to be very reliable
  • Don’t rely solely on manual testing – build an automated test suite
  • Focus on functional (black-box) tests, not just unit tests
  • Use a test database that can be reset; include regression tests for past bugs

5. Deploymemt

  • Decouple your API from other server apps: keep the API as a separate module.
  • Why? So updating or deploying one part doesn’t risk breaking everything else.
  • Independent deployments make development and operation safer and simpler.

6. Other Good Practices

  • Be consistent in resource naming: choose either singular or plural for your endpoints (/car vs /cars), but don’t mix.
  • For PUT or PATCH requests, return the updated resource in the response so clients know its new state.
  • Avoid using multiple forms of authentication or session mechanisms: for example, don’t mix custom tokens with default PHP session cookies (PHPSESSID) — it leads to confusion.
  • Don’t leak internal errors (e.g., SQL errors) to API consumers. Log the details internally, but return a generic 500 error externally for security reasons.

Why This Matters

  • The article is very practical: instead of rehashing REST theory, it focuses on avoiding pitfalls the author has personally encountered.
  • By planning, specifying, versioning properly, and testing early, you build a more stable and maintainable API.
  • A thoughtful deprecation strategy and good error-handling also improve reliability and developer experience for your API clients.

From the blog CS@Worcester – Nguyen Technique by Nguyen Vuong and used with permission of the author. All other rights reserved by the author.

Blog Post for Quarter 3

November 16th, 2025

Considering how clean code was recently on my mind (mostly due to a recent assignment), I thought it might be interesting to look into. I ended up finding out that there a various style guides (well, a comic from an assignment also showed me that too) and this blog shows some examples. It is nice as a basic overview of some style guides. It most notably noted 3 types of styles that revolve around whitespace usage and brace placement. It compliments what I was learning in class as the class typically focused on things like function and variable names, reducing the amount of nested loops, and the usage of too many parameters. The blog goes over how some styles place braces in a way to make it easier to parse through things like heavily nested loops and such. These both end up telling of ways to increase clarity but in different ways, which is super fascinating.

Interestingly, this led to me to look at my own code. My current code uses the “Allman” style of braces. This was taught to me back in AP Computer Science back in high school. I vaguely remember “Allman” being discussed in class, but I never made the connection between it and how I typed code. I ended up doing it since it was the easiest to read. Well, that and the professor told me that this was the “proper” way to code. (I vaguely remember the thing I did code in also automatically did it for me too.) Since then, I’d sometimes just go around and putting braces in that format. (Perhaps I’m worse off due to this since I overly rely on a style. I’ll need to learn to read other styles soon.)

Overall, I’ve mainly noticed my code is super, super bad. Like, overly bad. So next time I code something, I should do many different things. This blog I picked and the assignments on “clean code” would be a good start honestly. (Unfortunately, as someone who “thinks by doing,” I had a habit of creating copious amounts of technical debt without even realizing it. Then again, I was always the type to prefer redoing things entirely as opposed to looking for minor improvements….) Maybe one day my code will be actually good for once. And thankfully, I’ve got various places to start improving. There’s a long road ahead…. Well, at least that means that I have a lot of ways I can improve; the plateau isn’t here just yet. In fact, it is very far from where I am.

https://iannis.io/blog/the-ultimate-code-style/

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

CS343: The Dark Days of Design (and DDD)

This week I read a blog post from Robert Laszczak of Three Dot Labs titled “Software Dark Ages”. You can find that post here.

If the Dark Ages happened a long time ago, why are people still using Eclipse?

What was the article about?

Laszczak recounts his experience working for a company heavily ladened with pretty much every single kind of organizational, institutional, architectural, and technical flaw or burden out there. In his retelling, even something as simple as changing the functionality of a button would take months because of extremely high code coupling–among myriad other problems.

The way he solved this problem was to use DDD, or domain-driven design. DDD, like the similarly named test-driven development (TDD), places foci on particular problem domains and builds up around them. In TDD, these foci would have been our tests and test coverage, which we would then use to build up our code against. In DDD, we start with the problem and come up with a solution pattern that perfectly encapsulates the problem and its who/what/why/whatever.

If this sounds deceptively intuitive, that’s because it probably is. As Laszczak points out, DDD and problem-solutions like it have existed for almost two dozen years at this point (DDD’s whitepaper dates to 2003). The reason why they’ve fallen into obscurity is because people have forgotten the enlightened ideas of antiquity like they’re living in the Dark Ages.

In [the] Software Dark Ages, infrastructure is putting down important software design techniques.

The problem is, Laszczak bemoans, that the modern software DevOps team is more concerned with achieving technical marvels (e.g. getting that Atlassian Certified t-shirt) than spending their brainpower on something as simple as considering the wheel. Technology is great, except why are we using it? What purpose does it have, not only for us, but for our customers?

The reason we engage with structural criticism is to gain a better understanding of the system at play. Look at 432 Park Ave in NYC and you might see what a poor grasp of domain causes for a project, and when engineers are aware of the customer and their problems but choose to ignore both because… it was easier?

432 Park Ave: A beautiful marble-like white concrete exterior dominates the New York City skyline…
…except for the bughole voids and the hilariously slapdash Blu-Tak patch-and-fill job. A beautiful mess.

Why does DDD matter & why did I choose this post?

We have many frameworks for tackling software problems and organizing work, but very infrequently do we stop to consider the intricacies of the problem and how we can shape our project to meet the problem’s needs (inputs) rather than our organization’s abilities (outputs). Having high productivity and a strong team culture is important, but what does that mean if our codebase is in a terrible shape and our customer’s final product isn’t right-sized to their needs?

In our class, we’ve begun to work with Thea’s Pantry, and one of the things we’ve touched upon time-after-time is that the state of the system is specifically tailored to the needs of the pantry. Not all pantries–not a lot of pantries–the code we are looking at is the way it is because someone or something at Thea’s Pantry needed it to be that way.

That’s what thinking in terms of DDD yields us.

What not thinking about DDD yields:

  • 432 Park Ave
  • The Torment Nexus (NB DevOps: not an Atlassian product, don’t try it!!!)

What I think: DDD is a mouthful.

Kevin N.

From the blog CS@Worcester – Kevin D. Nguyen by Kevin Nguyen and used with permission of the author. All other rights reserved by the author.

OpenAPI and Cloud POS

I came across an article from Oracle that talks about the benefits of a cloud POS system that uses an OpenAPI backend. It starts by highlighting the importance of having a cloud POS system in a restaurant. The biggest benefits are its responsiveness, scalability, and security. It allows businesses to add and drop menu items with ease, and prioritize orders in the kitchen. It comes with built-in analytics to help them make decisions. Oracle tells about how Simphony, their cloud POS system, has local storage to allow the system to continue working through internet outages. Next, they compare OpenAPI to private API. The main difference is that OpenAPI allows for developers to connect the software more seamlessly with less restrictions. Private API, on the other hand, is only really available to internal developers, making it less user friendly. They then talk about how Simphony is built on OpenAPI architecture, making it easier for the customer to interact with, getting data and feedback quicker. This makes for a more trusting relationship between partner and client. They make a point that it provides both scalability and security. OpenAPI is flexible and responsive, giving businesses that choose to use a POS system with open API architecture an edge. In restaurants specifically, it allows for the front of the restaurant to connect with the kitchen more easily.

The reason this was important for me to read and write about is that we are spending a lot of time in my CS343 class discussing OpenAPI. It isn’t the easiest thing to grasp, but the more we learn about it, the more interested in it I am. This was especially interesting to me because Oracle is a very big tech company, and I was curious to see how they marketed their product that uses OpenAPI architecture. As we are learning about OpenAPI systems through real-world applications, it is always interesting to see how these things are applied in a real work environment. A POS system is a very appropriate use for OpenAPI. I enjoyed learning about the different types of products that Oracle offers using OpenAPI architecture. It was also cool to see how a company like Oracle uses OpenAPI and encourages their customers to use their products with it as well. It is reassuring to see how wide-spread the use of OpenAPI is. This encourages me to learn more about it in the future, and to make sure I am well versed in this subject matter.

https://www.oracle.com/apac/food-beverage/restaurant-pos-systems/simphony-pos/why-choose-cloud-pos-system-open-api/

From the blog CS@Worcester – Auger CS by Joseph Auger and used with permission of the author. All other rights reserved by the author.

Better your Coding Standards

For this quarters blog, I decided to write about Coding Standards and chose to read Why You Need Coding Standards by David Mytton. To start off, Mytton talks about what does “proper” code really mean. It is not just any code that works, but rather code that is easy to fix, add to, and update in the future. His blog mentions a common problems that we face today. Many developers start learning code with their own style which only they might understand. Once a project grows and other people join in, different styles will collide and make the code confusing. Mytton explains the frustration of working with messy code and how stressful it is to scroll through long, unclear code with confusing variable names, missing comments, and code without spacing.

There are two main examples that were used to show the difference that coding standards make. Both examples were written in PHP, the first example was messy. There wasn’t spacing, variable names were unclear, no braces around control structures, and long conditions missing parentheses. Although it technically worked, it was definitely hard to read at first. The second example showed the same logic. This time around there was clean formatting, clear variable names, proper indentation, and braces correctly placed. I’ve never used PHP but it was obvious that the second example was much easier to understand.

I selected this blog because recently in class we’ve been working on clean coding and realized how hard it can be to understand code written in different ways. I also wanted to further my understanding of how professionals handle this problem and how they keep projects organized. I think that this blog was able to explain that point in a simple and relatable way for me.

From this blog I learned that coding standards are beyond just “good habits.” It prevents confusion, reduces mistakes, and allows projects to run more smoothly. I also learned that a coding standard is not something that just one person creates and uses for themselves but rather by the whole team. I hope that I am able to fix my poor coding habits and write code that allows others to collaborate with my work. I think before this, I didn’t care much whether somebody would be able to read my code but rather if it was able to run then I was satisfied. My mindset has changed and I want to be more consistent with following coding standards.

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

CS343-01: Third Quarter Blog

Software Constr – Blog Three

APIs are something we come across a lot, especially the openapi.yaml file we look at for the Microservices Activities in class. So, I wanted to make a note for myself on what APIs are, the benefits, and the different types.

Firstly, what is an API? API stands for Application Programming Interface and it’s a mechanism that helps two software components communicate by the use of definitions and protocols. “For example, the weather bureau’s software system contains daily weather data. The weather app on your phone “talks” to this system via APIs and shows you daily weather updates on your phone.” And there are four different ways an API works: SOAP, RPC, Websocket, and REST.

The SOAP API is short for Simple Object Access Protocol API and it works with the client and server exchanging messages and other the use of XML. Remote Procedure Calls, RPC, APIs has the client complete a procedure on the server in which the said server would send back an output. Websocket APIs use JSON objects to pass the data being used and supports a two-way communication between the client apps and the server.

REST API is one we had just worked with in class and had homework on. It’s the most popular since it’s flexible and has the client send a request as data to the server which starts to use internal functions to return outputs back to the client. REST stands for Representational State Transfer that defines functions such as GET, PUT, DELETE, etc., all of which we have seen in the openapi.yaml file.

The REST API has four main benefits: integration, innovation, expansion, and ease of maintenance. Integration is used to increase development speed since the functionalities won’t have to be made from scratch because of the fact that APIs are used to integrate new applications with existing software systems.

Innovation is where industries can change with new arrivals of apps entirely since they can make changes without having to rewrite the entire code at the API level. “Businesses need to respond quickly and support the rapid deployment of innovative services.”

Expansion is something where it’s a unique chance for businesses to meet the needs of their customers across so many different platforms. “For example, maps API allows map information integration via websites, Android,iOS, etc. Any business can give similar access to their internal databases by using free or paid APIs.”

And finally, ease of maintenance. REST APIs act as a sort of gateway between systems. They each make changes internally so that the API isn’t impacted and in response? “Any future code changes by one party do not impact the other party.”

Source: https://aws.amazon.com/what-is/api/

, ,

From the blog CS@Worcester – The Progress of Allana R by Allana Richardson and used with permission of the author. All other rights reserved by the author.

CS348-01: Quarter Three

Software Process Management – Blog Three

In class, we’ve been learning about clean code and heard the name “Uncle Bob” multiple times. Because of this, I was trying to learn more about him and what else I could from clean code. Which led me to the SOLID Design Principles.

To start, Uncle Bob is a man named Robert Cecil Martin who had been born on December 5, 1952, according to Wikipedia and many other sites I had looked at. He is an American software engineer, instructor, and author – most recognized for promoting many software design principles and for being an author and signatory of the influential Agile Manifesto. He authored many books, articles including being the editor-in-chief of a C++ Report magazine, and was the first chairman of the Agile Alliance. He actually was self taught and joined the software industry at the age of seventeen. “Martin is a proponent of software craftsmanship, agile software development, and test-driven development. He is credited with introducing the collection of object-oriented programming (OOP) design principles that came to be known as SOLID.”

What is SOLID? Well, it’s an acronym for the five different object oriented design principles that Robert C. “Uncle Bob” Martin had created. In this acronym, there lies the Single Responsibility Principle, Open-Closed Principle or OCP, Liskov Substitution Principle, Interface Segregation Principle, and finally Dependency Inversion Principle.

One of the principles, the Open-Closed Principle, was something that I remember learning in class, even having to refer to it for a question in an activity we did. Modules, classes, and functions should be open to extensions, but closed for modifications. The rest however? Those were new and at first glance, my immediate thought was to Google it.

According to Wikipedia, the Dependency Inversion Principle or DIP is “a specific methodology for loosely coupled software modules. When following this principle, the conventional dependency relationships established from high-level, policy-setting modules to low-level, dependency modules are reversed, thus rendering high-level modules independent of the low-level module implementation details.”

The Liskov Substitution Principle in the source says that “if class A is a subtype of class B, then we should be able to replace B with A without disrupting the behavior of our program.” It was actually initially introduced by a woman named Barbara Liskov in 1987 where it was based on sustainability so that nothing would break.

Barbara Liskov is an American computer scientist who was a pioneer contributor to many programming languages and distributed computing. Some of her most notable work includes “the introduction of abstract data types and the accompanying principle of data abstraction, along with the Liskov Substitution Principle, which applies these ideas of object-oriented programming, subtyping, and inheritance.”

Source: https://medium.com/@lavishj77/solid-design-principles-dd3c0afe7e97, https://en.wikipedia.org/wiki/Robert_C._Martin, and https://en.wikipedia.org/wiki/Barbara_Liskov

, ,

From the blog CS@Worcester – The Progress of Allana R by Allana Richardson and used with permission of the author. All other rights reserved by the author.