Week-15: 12/21/2024

It’s easy to get something functional, but is it good? The book “Clean Code” by Robert C. Martin shows how my past coding techniques were wrong. This book isn’t just about making code work; it’s about crafting code that is understandable, maintainable, and, dare I say, beautiful.

The book highlights the importance of seeing code as a kind of communication rather than simply computer instructions. It’s about creating code that’s simple to understand, alter, and, ultimately, live with. The book provides several definitions of clean code, including the following: elegant, efficient, simple, straightforward, and carefully crafted. It also covers ideas and practices including utilizing meaningful names, constructing concise functions, correct commenting, formatting, error handling, unit testing, and so on. The book depicts the transition from sloppy to tidy code. It also includes a collection of code smells or heuristics that might help you write better code. 

I chose this book because I often find myself spending more time deciphering what code does than actually adding new features. I was looking for guidance on how to avoid creating such a mess and to understand what makes code easy to work with, and the book seemed highly relevant to my goals as a student. I also appreciated the idea that code is read far more often than it is written, so making it easy to read is very important.

This book has opened my eyes, particularly to the importance of code readability. It is not enough to have code that is functional; it must also be understandable to everybody who will work with it. This is particularly crucial in collaborative efforts. The author’s description of “code sense,” a carefully developed feeling of ‘cleanliness,’ struck a chord with me. Knowing that code should be clean isn’t enough; we also need to learn how to make it clean. 

I will be putting the principles of “Clean Code” into practice by always striving to leave the code cleaner than I found it. I also plan to be more diligent in naming variables and functions, keeping functions short and focused, and implementing tests to validate and describe code. This book has taught me that clean code is more than a nice-to-have; it is an important component of becoming a professional software developer. I now recognize that “working” code is only the first step; “good” code needs ongoing attention and effort. I’m excited to implement these concepts into my future projects, not just to improve my grades but also to gain more experience programming software.

Book: Clean Code: A Handbook of Agile Software Craftsmanship by Robert Cecil Martin

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

The planning process is an open source project is often created and monitored by the maintainers. This blog intends to go over the commonalities found by Safia Abdalla in open source planning mentioned in her article “Open source excursion: The poetry of planning”. I chose this topic because it relates to both the section in class where we went over licensing, which included open source licenses, and the section where we over different planning philosophies like scrum.

The first shared tendency between open source maintainers Abdalla lists planning with the intent to build excitement in the community that might hold many of your future contributors. Maximizing the outreach your plan gets among possible contributors and consistently providing updates when changes are made attracts attention towards your project, increases your chances of acquiring new contributors, and encourages existing contributors. Another common planning practice Abdalla lists is planning to prioritize. This planning method aims to optimize the process by which user requests and pull requests are fulfilled by distributing the responsibility among a chosen team. This allows for the efficient processing of requests, as well as allows many members of the team to get well acquainted with the user community and their hopes for the team’s project. The last 2 planning methods listed by Abdalla are planning to communicate and planning incrementally. Planning to communicate is a method of planning that, once a projects priorities and goals are well defined, aims to communicate those goals with the community. This leads to more exposure for the project, and possibly more support and contributions to it as well. Planning incrementally is a planning method where members of a team are mindful of the dynamic nature of the planning process, and communicate to the communities interested in the project the same thing, as to not mislead them.

Overall, these commonalities between open source planning all seem like good habits, and practices that would be useful for me to employ as a future open source project maintainer, and would also be useful as a contributor to open source projects to be aware of these tendencies so I can better align my work to the maintainers’ planning strategies. Planning with the intent to build excitement, along with being an effective planning strategy, sounds like it would also help for beginner developers to build a presence for themselves in the communities that are interested in the project that’s employing it.

https://increment.com/planning/open-source-planning/

Link to source blog:

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

Code visibility or the lack of it can introduce many problems that hinder the development process of a project. Some problems that can stem from poor code visibility include the misunderstanding of the function of the code or large portions of it, not defining possible conflicts well enough to avoid future features including them, and generally consuming an unnecessary amount of time. In Allison Wheeler’s blog, “Maximizing developer productivity with code visibility: A Complete Guide”, Wheeler goes over some other possible complications that could arise from poor code visibility, and presents tools like GitKraken as solutions to those complications. I chose this topic as it relates to the importance of clean code and other coding conventions we covered in class.

Wheeler presents the problems of poor code visibility as 3 main points; Lengthy prep time, Risk of conflicts or redundant code, and slow bottlenecked code reviews. The issue of length prep time arises when the function of the code or portions of it isn’t clearly stated and is left to the developer to figure out via time consuming methods, like trial and error. The issue the risk of conflicts or redundant code is related to the previous issue, where, because of time constraints and poor code visibility, the developer has an incomplete understanding of the code’s function, therefore not seeing how an added feature would be redundant or introduce a conflict. The issue of slow bottlenecked code reviews is also related to the misunderstanding of the code function, as when quality tests are conducted to test a change, a misunderstanding of the function of the unchanged code will result in an inaccurate quality test related to a new change. A solution to these problems is presented by Wheeler in the GitKraken DevEx platform, which is a technology with the aim of making the codebase of a project more accessible and decipherable.

Some of the features that improve code visibility include the creation of workspaces, which forgo the need for newly onboarded developers to access repos through the directory and organize all relevant repos in a single space. This removes possible confusion new hires could have with which repo to commit to. Another feature that improves code visibility is the launchpad feature, which organizes inter-repo requests, like merge, push and pull requests, into one space for the user to view. This feature allows developers to see which issues are being worked on and where the progress of the fixes for these issues are.

I can already tell that this information will be useful to me in my professional career, as many of these features resemble those that were in gitpod as we used it in class. Platforms like these seem very useful for streamlining the development process.

Link to source blog:

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

For my first blog I decided to talk about how individual contributors can best fulfill their role in the process of developing a project. This is relevant to the course material because the role of an individual contributor, which is mostly to improve the code and coordinating teams of other ICs, is a similar role the members of a development team would have in sprint.

The position that ICs occupy in most projects is a very impactful and influential position, aside from their ability to directly change the code. Despite their limited access to the management side of most projects, their proximity to the code gives them unique perspectives on the possible directions project could take, and what is and isn’t feasible to implement. In David Noel-Romas’ blog “An ICs guide to roadmap planning”, he introduces the problem of the IC who wishes they had comparable influence to the planning process of the project to their influence on the state of the code. Romas’ suggests several solutions to this problem, including identifying stakeholders and planning around the potential impacts the project will have on them through feedback and other means, making sure the management end of the team is aware of your visions for the project and when would be the most convenient times deliver updates and new features, and rationally bounding the work your team can do in the given amount of time, making an effort budget and working according to it. I think these solutions all take care of the problem of an IC who feels they aren’t offering enough input to the planning process well, and do so in a manner where the team dynamic isn’t compromised.

One of the reasons I think these solutions are effective is because they lend themselves well to the team structure of popular development philosophies. For example, if a development team is using scrum, there are points in the development process where an IC and their team can convene with the rest of the team members, like the sprint review, and offer their opinion on the direction and feasibility of the changes desired by other members of the team. The sprint review also allows the ICs to communicate with shareholders and assess. Since there are multiple sprint reviews per project, this allows many chances for an IC to offer their opinion on the planning process.

I can definitely see where this information will be useful in my professional career, as development philosophies like scrum are commonly used, and the input of an IC in the planning process can be essential to delivering a well made product.

Link to source blog: https://increment.com/planning/individual-contributors-guide-to-roadmap-planning/

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

For anyone who codes a  program, it is important to not just have a working program, but to have  a  program  that is   easy to understand, whether you publish your program onto github, or you want to  review  your program after finishing it. Clean code is a term that was first introduced by Robert Cecil Martin, also known as Uncle Bob. He wrote a book that gives best practices and tips for writing understandable and working code. 

When creating formulas for writing code, instead of including numbers in a formula, which could lead to confusion for  a number’s purpose in   a calculation. Creating   a variable that explains it’s purpose in a code makes calculation clear. Comments can explain the meaning of a statement in a  code,  and while comments can  attempt to clear up any confusion for anyone viewing code, it should not be used to explain a obvious statement, but to explain certain actions  in code. For constructing functions, it’s best to have a function perform one action, and if a function is very lengthy, a function should be broken down into multiple functions. 

When writing code with multiple nested if else conditions,  to  make a program easier to understand,  if else conditions should be split  into descriptive functions. As someone who has worked with different programming languages, I would want to use the practices of clean code, to write a working program that I can review and understand if i revisit my work.

What Is Clean Code? A Guide to Principles and Best Practices

From the blog CS@Worcester – jonathan's computer journey by Jonathan Mujjumbi and used with permission of the author. All other rights reserved by the author.

Introduction

Version control is important for modern software development, enabling teams to collaborate effectively, manage changes, and maintain code quality. The blog post “Version Control Best Practices” by Tobias Günther offers 10 tips on how to use version control systems (VCS) like Git more efficiently.

Summary

The blog outlines essential best practices for working with version control systems, focusing on enhancing productivity and reducing errors. There were ten points but here are the top 5 most important in my opinion:

1. Use Branches: Branches allow developers to isolate changes, experiment, and test without impacting the main codebase.
2. Commit Often: Regularly committing small changes ensures incremental progress and simplifies debugging.
3. Write Good Commit Messages: Clear, detailed commit messages help team members understand the context and purpose of changes.
4. Go Beyond the Basics: Developers should invest time in learning advanced Git features like interactive rebases and cherry-picking to enhance their workflows.
5. Don’t Commit Half-Done Work: Each commit should represent a complete, functional unit to maintain repository stability and clarity.

Why I Chose This Blog

I chose this blog because version control is a fundamental skill for software development, yet its nuances are often overlooked in coursework. While I’ve used Git for assignments, I realized that my approach lacked the deeper understanding laid out in this blog.

Reflection

There was a big emphasis on commits, which makes sense as commits are an integral part of version control and most of the tips talked about in the blog are practices that I do regularly, such as writing good commit messages. I don’t think it’s particularly hard to understand these standards for version control, and once you know them it’s just the norm to follow them.

Branching was something that I hadn’t known about prior to learning about it in class, but it makes sense to separate each new feature into its own area to work on instead of putting everything in main. This “tip” is really just a necessary way to stay organized and keep the repository and its pull requests in order.

Going beyond the basic features of git like committing and pushing is also a great tip, because although you could navigate git with only the basics, learning the more advanced features like rebasing can help greatly in certain situation where you’d be happy you know how to do it.

Future Application

There were some takeaways from this blog that I could incorporate into my own workflow. I think that I should commit more often than I do. I tend to forget to commit and only do so when I stop working but by then there could be a few features that are all crammed into one big commit. 

Citation

Version Control Best Practices by Tobias Günther

https://www.git-tower.com/blog/version-control-best-practices/#8-agree-on-a-workflow

From the blog CS@Worcester – The Science of Computation by Adam Jacher and used with permission of the author. All other rights reserved by the author.

For my final blog post for the semester, I wanted to pick a topic that was different from project management, since I had already written about that a few times. Since our most recent topic in class revolved around GitHub and git commands, I wanted to explore a blog post that aligned with that topic. I came across a blogpost by GitHub staff engineer Sarah Vessels, from the github.blog page, about code review.

In this article, code reviewer Sarah Vessels discusses some practices to help improve code reviewing and make it more useful and efficient for everyone involved. She advises constantly checking your GitHub notifications inbox, anytime you have a spare moment. She also recommends using GitHub Slack Integration. Certain queries can help filter a slack group for finding outstanding pull requests that need review. We used Discord for our class instead of Slack, but as I understand it, Slack is more common in the professional world. I believe Discord has equivalent queries that can be used, anyway. The next piece of advice she gives is to use reviewer teams to manage notifications. While catch-all code owner teams can be okay as a fallback, it’s better to keep the number of code owner teams your own small, so that anything you get pinged for or anything that shows up in your inbox feels relevant to you, and not just something to ignore.

The next part she discusses, which I feel is the most important advice, revolves around giving good, constructive code review that doesn’t across as lazy. Good code review focuses on specifically saying,” I have a problem with this, maybe you should try xyz instead” instead of saying “I don’t like this” or “This won’t work” and leaving it at that. It’s good to ask questions, because the person who authored a pull request has more context for their changes, and gives them a space to explain and justify their reasonings. Personal preferences are fine, but approval should be about the overall integrity of the code. If the changes won’t break anything or affect production, leave the feedback with a comment but still approve the pull request anyway to keep the process moving. This is something I personally appreciate from the author, because while I don’t mind receiving feedback and improving my part of the process, I hate the feeling of holding back the overall process. This allows opportunities to open discussion without causing a holdup.

She has a few other suggestions in her blogpost, like being gracious and using draft pull requests, but I believe the most important things are her advice about the giving good feedback and managing notifications so you feel compelled to give every notification your full attention. I don’t know how much code I’ll be reviewing in the near future, but if I’m ever in this situation, on either side, this is good advice for me to keep in mind and remember.

Link: https://github.blog/developer-skills/github/how-to-review-code-effectively-a-github-staff-engineers-philosophy/

From the blog CS@Worcester – Justin Lam’s Portfolio by CS@Worcester – Justin Lam’s Portfolio and used with permission of the author. All other rights reserved by the author.

Scrum is a framework that teams use to organize themselves in a project to reach a common goal. The values that members of a scrum team value are commitment, courage, focus, openness, respect. Scrum team is open to new ideas and opportunities, respecting each other, and have patience for the scrum process, and focusing on time-consumed tasks, and finding space for improvement. 

Scrum deliver a product for customer in a time period called a sprint. Product Backlog is the to-do list for a team which contains the requirements for a project. Product owner, which is one of the scrum roles, is responsible for maintaining and adding updates for the list, removing and adding new requests from customers. Sprint backlog is lists of items from the product backlog that is worked on during the current sprint. Increment is the end product of a sprint. 

The product owner guides the team on the next steps in the scrum process and ensures that the team understands the requirements that a business or client wants. The Scrum leader is responsible for making sure the scrum team works effectively. When working in a scrum team, there are different types of events that the scrum team is involved in.  Sprint planning is when teams estimate how much work needs to be done in a sprint. Daily Scrum is a short meeting where team members plan for the day, and provide updates on challenges experienced, and what work has been done. Sprint Review is the period at the end of the sprint, where the team reviews the work that has been completed, and presents it to stakeholders. Sprint Retrospective is when a team comes together to discuss the sprint result and make adjustments for future scrums. 

This semester in  CS 348, I had learned about scrum. With learning scrum, I was able to see how software team deliver products for clients. 

What is Scrum? – Scrum Methodology Explained – AWS

From the blog CS@Worcester – jonathan's computer journey by Jonathan Mujjumbi and used with permission of the author. All other rights reserved by the author.