Mini Work-term Report 2 (WTR)
A Comprehensive Review of My Co-op as a Solutions Developer
Introduction
In the tradition of UWaterloo’s WTR (Work Term Report) writing, I decided to write another report to summarize my PHRI Co-op placement. The first WTR is an interview with my product manager Les. Unlike the traditional Waterloo WTR, I will follow a different structure started with an introduction to the institution and my work. Then, I will share some unique cultures in our software engineering team as well as my strategies to be successful. Lastly, I will explore an engineering decision I made during this Co-op.
PHRI
PHRI stands for Population Health Research Institute, a joint institute of McMaster University and Hamilton Health Sciences. Housed in the state-of-the-art David Braley Research Institute, PHRI remains a top research institute in Ontario with research encompassing 1,500,000 participants in 102 countries on 6 continents. PHRI explores CVD, diabetes, kidney and lung diseases, brain health, cancer, the latest COVID-19 virus, and more with researchers from McMaster University and Hamilton Health Sciences.
Such great work must be fulfilled by an interdisciplinary team gathering talents from all across Ontario, and I am honored to be a part of the ROME team as a part of the ICT Department in PHRI working alongside world-class developers, business analysts, and product managers.
My Work
During this Co-op placement, I worked on project ROME (Research Operations Management Environment). For confidentiality reasons I cannot go into details about tech stacks and designs although they are interesting topics for discussion. An advertising page can be accessed here while I cannot share the URL of the product. Due to confidentiality reasons, I cannot share details regarding tech stack and architecture although they are interesting topics.
Although titled as a solutions developer, my work is still within the realm of full-stack web development. My work including migrating databases, developing SOP workflow APIs, enhancing validation, and optimizing multi-tenant features. I worked also touched on some core topics in web engineering including backend API design, frontend event handling, UI design, database development, authorization, validation handling, concurrency, data modeling, data transfer, software architecture, systems design and so much more. Aside from development work, a lot of time is dedicated to debugging, team meetings, and design.
Culture
PHRI is a research institution in the clinical research sector. Therefore, the team culture and structure are very different from a tech company. For confidentiality reasons, I can only give a high-level generic introduction to the special culture in a tech team in PHRI.
Reliable Tooling
Being a mission-critical product, ROME has adopted a very reliable tech stack that many might deem as “outdated.” This is probably one of the most important factors that set our team apart from a team in a tech company. In fact, older technologies are also widely used in web-based enterprise applications due to their constant upgrades and maintenance while newer tech stacks are common in startups. While tech stacks like MERN and MEAN are so popular in web development, they might be unstable in some circumstances, which are not suited to mission-critical systems in clinical research. A strongly-typed language that follows an Object-Oriented design paradigm will make a codebase less prone to bugs. A more stable package manager will bring more clarity in dependency management.
Auditing, System Validation, and Verification
Due to its importance as a mission-critical system, ROME has a lot of auditing and system validation features integrated into the system.
Auditing is a crucial component in ROME and other PHRI clinical research products. Documentation tools help to ensure the integrity of the research as well as the security of sensitive data. In addition to the features for clinical research management, ROME also has rich features to support auditing.
System verification checks compliance of each element of ROME in a consistent and reproducible manner whereas Validation ensures that the product meets customers’ needs. A lot of features are dedicated to the verification of different software artifacts while meetings and communications have been established for validation efforts.
Rigorous Code Review
After discussing the system-level validation and verification for ROME, it is also important for individual developers to maintain standards in their code. Therefore, the ROME team has enforced a strict code review policy for its developers. Developer has to maintain high level of cleanness and readability in their code while architects have to ensure the code in the system has high composability, interoperability, maintainability, extensibility, and evolvability. I was lucky enough to get involved in some development at the architect’s level and have made engineering decisions directly relating to these properties. Interestingly enough, many people argue that evolvability and extensibility are the same, but they are ignoring some differences only senior developers would know. Evolvability is a superset of extensibility in that extensibility considers simply whether the system can integrate a new module with similar designs whereas evolvability considers the system’s ability to integrate not only new modules but new tools or services that are designed very differently from the current system. In simple words, evolvability considers how well the system can adapt to new tools and frameworks.
Hardcore Business Logic
The core of ROME and other PHRI products is its business logic derived from PHRI’s 20 years of experience in clinical research. The vision of PHRI’s ICT team is to dedicate itself to improving the experiences of clinical research for research teams. The business logic are basically SOPs (Standard Operating Procedures), Randomization techniques, and Data Integration methods from a higher-level view. This package of knowledge is integrated into ROME to provide researchers with better experiences.
Comprehensive Reporting Services
Unlike tech companies that have data scientists who are more focused on delivering more profitable features, the ROME team strives to ensure the integrity and accuracy of the data. This is almost similar to a lot of consulting firms which also have projects in industries like healthcare, research, and financial services. Therefore, reporting services for clinical researches must be comprehensive instead of selective. In clinical research, any sample of data should not be neglected.
Strategies in a Tech Team
During this Co-op, I have acquired a significant amount of strategies to be successful in a tech team by exposing myself to different professional situations, engineering problems, and design challenges.
How to manage development work
This is the most important task for any developer not only because it affects an engineer’s productivity in his work but also because it involves many other skills like time management.
A. Modularize the work
I often start my work on a bigger feature by dividing it into a standard framework for web development consisting of several stages including — understand requirements, explore the context, migrate the database, create APIs endpoints, create page models, create web pages, glue components together, test out features, create middleware, create Pull Requests, resolve code review comments, complete Pull Requests. In each stage, I will deploy the PDCA cycle (Plan-Do-Check-Act) to ensure quality and efficiency. Special attention is paid to the check step in PDCA to ensure that no errors are carried into a new stage.
B. Manage the time
Each of the above stages takes about one to two days to complete. Managing time doesn’t always mean enforcing hard deadlines, but being flexible to achieve the overall deadline. Software engineering is a field that doesn’t allow the abrupt stop of the work because it’s likely that you will forget the dependencies of a bug or an idea of a solution. Therefore, in between each stage, I will include some buffer time to allow some stage to pass the deadline if they require more time. Some work like testing and gluing components together will take more time because they require looking at the feature holistically.
C. Document the work
Cannot find where you left off after a cup of coffee can be a pain when working on big features or modules. This is more likely to happen when you are dealing with several errors that are related to showing up at the same time. Oftentimes, quick comments will be a good tool to document the location, your idea, risk assessments. They are embedded in the code so they can provide you with insights about what you want to do or the risks involved.
How to communicate technical problems
Communication is one of the most important skills for software engineering. I have developed some tips to master technical communications.
A. Focus on the problem
It’s easy to diverge into a more generalized problem when two developers discuss an error. Debugging is an empirical activity, and developers often recall their own experiences instead of focusing on the problem. That’s also one of my flaws before. In this Co-op, I have learned to focus on the specific problem in the current context instead of dwelling on my past experiences. Experiences are helpful in assumptions of the problem, but it never helps to correctly assess the situation. Sometimes, it will be more helpful to discuss the error message, results in debugging tools, and patterns on diagnostic tools. These actions help to diagnose the problem.
B. Structure your message
I often structure my message into several components: a clear introduction to the problem, details to the problem, past actions on this part of the code, potential solutions, pros and cons of solutions, other implications.
Here is a typical message I would send to my colleague:
[Somebody], the list of vendors are not showing up under the vendor tab. When user save the Edit form, it should display a list of vendors, but now it only display “no records.” I have recently added some LINQ code to select the vendors’ id, name, countries, and responsibilities to be displayed on the modal. I also added some JavaScript code to direct the page to the list after submission of Edit form. I believe I can remove the LINQ code first to see if an simpler version would work, but that means I will lose that portion of code. Remove that code also means that I can’t use the selected vendor to do authorization, which is dependent on the data in the vendor.
C. Provide context
It’s difficult for someone who works on another corner of the codebase to know what’s going on on your side. Even if you describe the error in detail, it still might confuse them as they might not know the UI components, page model, and API endpoint logic. Therefore, it is important to fill the other person in on the situations on your side. When dealing with team members that are involved in non-technical work like product managers and business analysts, a developer should provide as much explanation on technical concepts as possible.
How to master status reports in meetings
Status reports are common in team meetings to show the other developers the work done. How to develop such status reports will not only leave you a good impression among developers but also will make the team’s work more efficient.
A. Focus on the functionalities of the feature
Status report usually comes with a demo. The most effective way to demonstrate your work is to show the key functionalities of the feature. Usually, in my team, other team members will be able to share their thoughts on the functionalities for future improvements.
B. Relate to the goal of the feature and product mission statement
Software engineering is very product-oriented. When doing status reports on your work, it is good to relate to the overall goal of this feature and how it contributes to the mission of the product. This will enable the team to do verification on the product — checking to see if the feature meets the requirements and if it will ultimately contribute to the product.
C. Include critical assessments on your work
Nobody is more familiar with the work than yourself. While the product manager and senior developers may sometimes provide constructive comments to improve your work, it is more important for the developer himself to evaluate his work. I always leave five minutes in my status reports to cover the pros and cons of the current implementation as well as future potential improvements.
Engineering Decision-making
Design under constraints and iterative design processes are keys to engineering. As engineers, we must make tradeoffs so that
In this section, I will explore an engineering decision during my Co-op by analyzing the requirements, assess the problem, evaluate different solutions, justify my final decision, and elaborate on my future improvements.
Requirements:
In a modal window, implement an input dropdown box that can create a vendor for a particular study. If the vendor doesn’t exist, let the user create the vendor in the modal instead of navigating to the admin area.
Problem:
Completing two tasks at once.
The requirements and system design require that the modal should contain both functionality of creating a vendor for a specific study and creating a new vendor as a role for the system. This is very difficult to implement because the UI component does not support the custom input of two data types — GUID when creating a StudyVendor and String when creating a Vendor. The two data types complicate the situation.
Constraints:
- No available custom components for changing types
- Have to consider validation (can’t validate loosely typed variables)
- Integration between ajax between front and backend
- Ensure Interoperability between modules
Solutions:
A. Allow two different data types
Pros:
i. Easier to implement
ii. Select the object correctly (use a GUID instead of string)
Cons:
i. Component can only bind one property
ii. Cannot validate two types invalidator
iii. Low interoperability with backend
B. Alter to a universal data type
Pros:
i. Compatible with the UI component
ii. Easier validation with only one type
Cons:
i. Not the correct way to retrieve data (with a string)
ii. The UI component wasn’t used correctly
C. Include data handling logic in the frontend
Pros:
i. Use proper customization principles
ii. Good data handling logic
Cons:
i. Not enough time to design and implement
ii. Complicates the validation logic
Final Decision:
Alter to a universal data type
At the time when this feature is required, there wasn’t enough time to design and implement the best solution — to use proper customization principles to implement data handling logic in the frontend.
The initial two data types solution does not work for the UI component because it can only take in one type of data. There’s also not enough time to implement a validation logic that supports two different kinds of data.
The universal data type solution will meet the requirement in a short amount of time while satisfying basic requirements.
Future Improvements:
As a note to future work on this feature, it will be better to design a customized solution that uses the existing UI component to the fullest capacity. A better solution in the long term is to write a completely customized UI component. This functionality will be widely used in other input forms. Therefore, it will be plausible to generalize the idea.
