Programming Over Time
Overview
This is our first post for the Fall 2024 Software Engineering class about the Software Engineering at Google book! This article will relate our work with GatorGrade with the practical skills featured in the “Programming Over Time” section of the book. Software engineering isn’t just about writing code — it includes the tools and processes an organization uses to maintain that code over time. As Hyrum Wright discusses in SE Radio 609: Hyrum Wright on Software Engineering at Google (00:50:37), “As you write software, think about how long this software has to last.” At Google, the focus is on whether the software will be needed for the next decade or just temporarily.Key Concept
Summary
Software Engineering is not just computer science. It involves the application of theoretical knowledge to build something real to be used by other developers, consumers, and anyone else who might be interested. With this in mind it is important to integrate the more rigorous engineering methods used by other professions to help improve the quality of code made by software engineers overall. With the helpful tips from the Software Engineering at Google book we will be able to make and improve features from GatorGrade with a lot more quality.
Software Engineering is not just writing the code but it is also all the tools and processes an organization uses to build and maintain that same code over time. For example, by working to update and improve GatorGrade’s features we are participating in Software Engineering and the GatorGrade legacy.
Our goal is to Make code valuable in the long term! Think 10-20 years from now after we have long graduated our code will still be used to grade students work and we have make sure we leave behind code that is readable and understandable. This highlights the importance of writing clear, maintainable code. In large organizations, code is often read and modified by many different people over time. As a result, making sure that code is understandable and well-documented is critical to the long-term success of a project. How will the code need to adapt over the length of its life? Take into consideration the future of the CIS department at Allegheny College and how future assignments might look. For example, integrating artificial intelligence (AI) into our code is something to discuss thoroughly especially now that professors are putting in their syllabus a statement about the proper use of AI. How will the organization need to adapt as it evolves. Will our system be able to handle more users or more collaborators? Can our system help with grading more types of assignments? As the CIS department grows in majors the variety in assignments will grow and it is important to consider the future major’s size and assignments. How are resources such as time or storage impacted by our decisions? Remember, it is important to come up with low cost solutions that still get the job done! The fourth principle which isn’t mentioned in the book but instead introduced in the podcast is “constraints”.“Code is written once but read many times” - Hyrum Wright
Three Fundamental Principles Software Engineering
Time and Change
Scale and Growth
Trade-offs and Costs
Constraints
(Hyrum Wright 00:48:50) Picking appropriate constraints as an organization scale is actually a really powerful way of enabling that kind of scalability. We kind of knew that going in, but it’s amazing to me how that came out in the book, whether it’s, again, large-scale changes or build systems or testing infrastructure or style guides. All those things benefit from having appropriate sets of constraints.
Quiz Time
1. Which way should we write our comments, functions, and variables in our code?
Bonus points How many things can you list to improve in both pieces of code?
# OPTION A
def best_function_ever(
names, something
):
files_list = []
# create a thing
for i in names:
# iterate through stuff
if i.endswith(os.path.sep):
i= i[0:-1]
# fix theee thing to be better.
i2 = i.replace(os.path.sep, "/")
thing3 = {
# Random Dictionary
i2: [
# Important strings!!! <----- Look at them
{
"description": f"Complete all TODOs in {i2}",
"check": "MatchFileFragment",
"options": {"fragment": "TODO", "count": 0, "exact": True},
}
]
}
...# OPTION B
def write_yaml_of_paths_list(
path_names: List[str], search_root: str
): # expected input: A path list
"""Write YAML file to create gatorgrade file and set default messages."""
files_list = []
# Create an empty list to store dictionaries
for file_path in path_names:
# Iterate through items in path_names
if file_path.endswith(os.path.sep):
file_path = file_path[0:-1]
# Convert file separators to '/'
file_path_fixed = file_path.replace(os.path.sep, "/")
# Make file_path easier to read by removing unnecessary characters
file_path_dict = {
# Dictionary to store the file paths
file_path_fixed: [
# List which stores strings which will be in gatorgrade.yml file
{
"description": f"Complete all TODOs in {file_path_fixed}",
"check": "MatchFileFragment",
"options": {"fragment": "TODO", "count": 0, "exact": True},
}
]
}
...Click to Expand for the Answer
Answer: B!
We should write our comments in a way that is informational and useful. Additionally, variables should be named in such a way that they can be related back and provide insight to the program. This will help with the sustainability of our project in the long run. If someone is providing maintenance, it is a lot more helpful to have named variables like output1 + output2 = ans than a + b = c.
The correct code is from GatorGrade! So exciting!
2. Pick from the list the fundamental principles to keep in mind when in the process of software engineering?
- Your pay per line of code
- Trade-offs and costs of decisions
- Knowing who is doing the most work
- Time and Change of software or needs
- Scale and Growth of organization
- Making your code not boring
Click to Expand for the Answer
Answers: Trade-offs and costs of decisions, Time and Change of software or needs, and Scale and Growth of organization
While developing GatorGrade and other software tools in its ecosystem, we will have to keep on mind these principles. First, of all the trade-offs our decisions are super important because certain functions may cost a lot of time or computer storage so making decisions that are low-cost but are also practical is important. Ask ourselves is there a way to improve this code either worst-case time complexity wise or by choosing better object types to suit the task at hand.
Secondly, we need to consider how time and change will impact our code. For example, will a software update break our code? Or are we able to set up an environment to prevent that. How will the needs of the class change overtime? Will GatorGrade need to be able to correct more than just Python in the future? The future of the software has to be considered throughout the process of development and deployment.
Lastly, how does scale and growth of the organization or user-base impact our code? If the CIS department at Allegheny College grows by 100 students are we able to handle that user-base? Or if we get more student develops to work on GatorGrade is our branch/fork/management system understandable enough to allow for more people to join our team? We want our code to handle lots of users and be able to understood by new developers at any time.
3. Which is the best commit message out of these options?
Bonus points How would you improve each of these commit messages?
OPTION A: make post better
OPTION B: add a summary and blog page
OPTION c: Answer: C! C is the best option because it is informative and uses the Conventional Commit specification. It is specific and descriptive which is important especially if you or another person are reviewing old changes. Descriptive commits can save time and resources when it comes to reviews and bug fixes. Other example key words that can be used for the front of commit messages are as follows (see if you can figure out what instance each is used for):feat(blog): add se1 page and write se1 summaryClick to Expand for the Answer
featfixdocsstylerefactorperftestbuildchorerevert
Reflection
Overall, it is important to consider the theoretical knowledge we know about the most reliable software engineering practices throughout the entire time we are working. It is important to make sustainable code that is readable and capable of being adapted.
Software Engineering is about programming integrated overtime so quality code and documentation take priority!Key Takeaways for Class Discussion
Action Items
It is important that throughout our time working on this project and beyond that we keep in mind writing quality code that is sustainable. It is important to hold yourself and your teammates to a high standard of code and documentation. Writing code that is understandable is key to making our tool capable of serving the Allegheny College community and beyond.