Before taking this class, I didn’t know of any guidelines for writing code. Clean code is a guideline with an objective to make code easier to understand, maintain, and read. By following its principles, a developer makes projects more likely to succeed in the long term. Learning this, I thought that I should try to implement this in all I code I make, and am still trying to make clean code practices common in my code. However, in a blog post: “Goodbye, Clean Code” by Dan Abramov, he says to “let clean code guide you, then let it go”. This was interesting, since wouldn’t having clean code all the time be nice to have for understanding the code you write? Dan during the time he recalls in the post thought so too.

In this post, Dan recalls a time when he was working on a project and checking his colleague’s code they had just turned in. The code had tons of repetitive code and math that would take a second to process. Bothered by this, he fixed it to look cleaner, removing the repetitiveness and making it so there could be changes in one spot rather than multiple methods. This resulted in a request that he reverts the changes he made from his boss, which he reluctantly agreed to do. Looking back at this event, the author says it took years to understand his boss was right. Calling clean code a phase of a coder’s life and explaining that chasing that guideline was forgetting about the human aspect of coding. Firstly, he changed his colleague’s code without discussion, which was a terrible decision when working in a team where they needed to collaborate. Secondly, he realized later that the changes he made would have impacted the project severely and added complications if he had kept them.

This blog post was not saying there was a problem with clean code itself, but how people treat clean code as an absolute guideline like the author did in the past. This post helped me understand chasing clean code is more of a detriment to yourself and others on your team and to not get too obsessed with it. Getting hung up on this aspect makes you lose sight of your project and team’s goals in mind. I think that people should keep writing clean code but not lose themselves to chasing a standard in a way that makes writing that code meaningless. While I haven’t experienced this, I can sort of understand it as how I was trying to implement these principles in my code after learning of them.

References: https://overreacted.io/goodbye-clean-code/

From the blog CS@WORCESTER – Leon's Blog by llai194 and used with permission of the author. All other rights reserved by the author.

Hey Coders! Feeling lost in a maze of confusing code? Tired of code messes and bug hunts?

Today, let’s dive into the exciting world of open-source scientific software. If you’re like me and tired of dealing with confusing code and chasing bugs, don’t worry! The article “Ten simple rules on writing clean and reliable open-source scientific software” by Hunter-Zinck et al. (2023) is here to show us the way to clean, reliable, and easy-to-handle code that benefits everyone.

Why This Article Rocks

This article stood out because it tackles two key issues: making code user-friendly and emphasizing the importance of open-source software. Plus, it simplifies complex software development into 10 easy-to-follow rules.

The 10 Golden Rules

The article outlines 10 key principles for writing clean and reliable open-source scientific software. Here’s a quick rundown, with a dash of my own insights:

1. Modularize: Break down your code into smaller, independent units. This makes it easier to understand, test, and maintain. Think of it like building with Legos – you can easily swap or add new pieces without affecting the whole structure.
2. Document everything: Write clear and concise comments explaining your code. Imagine someone completely new to your project needs to understand it – would your comments guide them through the jungle?
3. Use descriptive names: Don’t be cryptic! Choose variable and function names that accurately reflect their purpose. Think of them as road signs – they should tell you exactly where you’re going.
4. Test relentlessly: Write unit tests to catch errors early and often. These are like little detectives, constantly scrutinizing your code for any suspicious activity.
5. Version control is your friend: Use tools like Git to track changes and revert to previous versions if needed. It’s like having a magic rewind button for your code!
6. Automate your tasks: Write scripts to automate repetitive tasks. This frees you up to focus on the bigger picture and avoid tedious manual work.
7. Embrace continuous integration: Set up systems that automatically test and build your code when changes are made. This helps to identify problems early and prevent them from snowballing.
8. Get feedback: Share your code with others and ask for their feedback. This can be like having a team of extra eyes, spotting errors and suggesting improvements you might miss.
9. Contribute to the community: If you’re using existing open-source software, consider contributing back by fixing bugs or adding features. Remember, it’s a two-way street!
10. Stay up-to-date: Keep your codebase and dependencies up-to-date with the latest versions to ensure compatibility and security. Think of it like keeping your operating system updated – it’s essential for smooth sailing.

Learning and Beyond

This article has been a game-changer, offering a clear roadmap for writing clean and reliable open-source scientific software. Looking forward, my plan is to further refine my skills in writing clean and reliable code and actively contribute to the open-source community.

P.S. For more detailed explanations and examples of each rule, check out the original article here.

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

In the engaging podcast-style video, “Clean Code: Horrible Performance,” https://www.youtube.com/watch?v=OtozASk68Os&t=1944s two seasoned developers share insights over 47 minutes on the delicate balance between clean coding and system performance.

The developers initially champion the virtues of clean code—emphasizing readability, maintainability, and collaborative benefits. However, the conversation takes an interesting turn as they delve into the paradox that clean code might lead to suboptimal performance.

Real-world examples illustrate scenarios where an excessive focus on code cleanliness can unintentionally hamper efficiency. The developers caution against over-optimization and stress the importance of a balanced approach.

Practical insights emerge as the duo offers strategies for identifying bottlenecks and optimizing critical code sections without sacrificing readability. They acknowledge the evolving nature of software development, where the pursuit of clean code intersects with the demand for high-performance systems.

In conclusion, “Clean Code: Horrible Performance” serves as a valuable guide for developers seeking to strike the right balance between clean coding principles and performance optimization. The developers’ experiences provide practical wisdom for navigating the complexities of modern software development without compromising code aesthetics or system efficiency.

From the blog CS@Worcester – Dose Of Dev by msavice and used with permission of the author. All other rights reserved by the author.

This week’s blog post I decided to research more about linting for non-inclusive language. The medium I selected is a blog post by Michael Bachand, an engineer at Airbnb. “Building an Inclusive Codebase” dives into the techniques engineers at Airbnb are taking to make their work environment more inclusive for everyone. In order to create a more inclusive platform, the development team must also be inclusive. To start, the team has increased the diversity in their teams to accommodate every demographic. Bachand emphasizes that building a diverse team will help empower both Airbnb’s hosts and guests. Inclusivity goes beyond forming a diverse team however.

The team at Airbnb discovered an issue with non-inclusive language in their codebase. After working with employees affected by these terms, the team presented a proposal to the Chief Technology Officer of Airbnb and got the approval to refactor the code to be more inclusive. Michael Bachand stresses that “acknowledgement and resourcing from the highest levels of management legitimized this effort”. The support from management and the CTO prioritizing the task produced a healthier working culture across all teams.

Airbnb’s development team broke down this problem into two key parts: preventing the use of this language and eliminating the existing language. One essential tool that was utilized was the woke linter which checked each pole request for non-inclusive terminology and suggested alternative terms to promote belonging. The team now had a proper tool to use, however, they didn’t send the tool to every developer immediately. The team took a unique approach by slowly distributing the tool to expert developers. These developers decided which directories the linter should access and which should be excluded.

Before our in-class activity on this topic, I never thought about how my sentences might unintentionally offend or upset someone. This topic has opened my eyes to how crucial having a linter tool is. Many of these non-inclusive terms sound offensive without the right context which is why every developer should utilize a linter of sort. Reflecting on the problem addressed by Airbnb, having the support from the CTO is reassuring to know that your work is valued by the company. I believe all companies should strive to create a sense of belonging in their work environment, no matter how big or small. I can confidently say that the information I learned today will stick with me for the rest of my career.

Blog Post: https://medium.com/airbnb-engineering/building-an-inclusive-codebase-bbaa2315e5b8

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.

Not too long ago, I learned about the “Agile” methodology for the first time. I learned all about how following “Agile” allows for code that is always functional and that can be built off of in a much more proactive way than that of code produced through the waterfall approach. What I did not learn as much about, however, is the impact that following an agile methodology has on the customers, the vendors, and the project manners, as many of the lessons I took part in were developer-focused.  

In order to learn more about the impact of the Agile methodology project members, other than developers, I did some research and came across a blog post titled: “8 Benefits of the Agile Methodology” by Erin Aldridge. This blog post takes the approach of describing the benefits of using an agile process through the perspectives of people who would otherwise not be working directly with the code. 

CUSTOMER BENEFITS:

The article identifies the way in which incremental delivery of a project often results in higher levels of customer satisfaction, as well as provides greater customer involvement and input on what they are looking to receive as a final product. This higher level of customer satisfaction is also paired with a higher return on investment for the customer.

VENDOR BENEFITS:

From the perspective of a vendor, it becomes much easier to ensure a high-quality product, or a product that satisfies the customer when a new increment of the product is available at the end of each sprint. Increased level of transparency on the progress being made on any given project also allows for a vendor to more effectively work with a small-sized team and communicate in meaningful ways with the customer. 

PROJECT MANAGER:

While working with “Agile”, developers are able to get right to working on a project, cutting out much of the uncertainty that may be created as a project manager attempts to figure out all the parameters for the project. Project managers are also able to better select tasks to be prioritized first, and will find it much easier to keep track of project progress through the points emphasized during each daily scrum meeting. 

From what I have discovered, using “Agile” seems to be better for every member of the development process compared to other methods like the “Waterfall” process. I have also learned through this research that implementation of the agile methodology is more simple than often thought and improves nearly every aspect of the work process (as mentioned through points above). To add to this, I also now have a better understanding of the role everyone plays as described by someone who actively uses “Agile” in a real workspace. In fact, I now believe that the agile process is easy enough to implement that I will very likely recommend its use in future projects that I take part in. 

Blog Referenced: 8 Benefits of the Agile Methodology – Project Management Academy Resources

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

In many of the previous classes that I have taken throughout my college process, I have been tasked with writing code. However, in nearly all of the assignments I have received so far, instructions only require the code to be working or at most want there to be comments to go along with said code. After reflecting on this fact, I began to think more about how there must be some sort of standards for writing code; some sort of quality control when it came to preparing code for use in a professional environment. This is where the practices of writing “clean code” come in.

Recently, I have read a blog post called: “Writing clean code: best practices and tips for developers” by René Cadenas, in which the author went on to outline several key points to follow when improving the readability and cleanliness of code. I chose to read this article in order to develop a better understanding of the topic covered in class, as well as to create a better understanding of how I can implement the use of clean code practices in future workspaces.  “Clean code” is defined here as “code that is not only functional but also easy to read, understand, and maintain”. The author also wrote about why clean code matters, claiming that it leads to improved collaboration between developers, and that implementing defining features of clean code, like meaningful naming conventions, proper documentation, and reusable code blocks that don’t require other developers to repeat efforts and redundancy, will all lead to a final product that follows the principles of writing “clean code”. Other topics of emphasis in the blog post were: consistency of code, clarity of comments, and efficiency of the code written.

After having read this blog, and through our classes in which we had our own lessons of writing clean code, I now understand why it is such an important aspect of writing code. After reading the article, I learned about how much of a difference refactoring code can actually make when it comes to the readability of code, which I didn’t consider throughout our in class discussions. After seeing examples of refactored code alongside the same code in its non-refactored form, it really convinced me to try harder to implement these practices in my own writing of code. Moving forward from this point, I want to put a lot more thought into how I write my code and whether other people are clearly able to understand it in the same way that I view it. After all that I’ve seen on the topic, I think the best way to go about this is through practicing more on implementing these “clean code” practices in my own work. I think it might even be a good idea to use a separate “clean code” guide to double check code I write in the future before submitting it. 

Blog Referenced: https://blog.elaniin.com/writing-clean-code-tips-for-developers/ 

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

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.