In my latest work on Trendwatch, I’ve been refining both the feature implementation process and my approach to managing commits. Every development cycle brings new insights, and this time was no different. Below are some key lessons learned and the competencies I’ve reinforced along the way.
Lessons Learned
1. Structuring Commit History for Clarity
During development, I initially focused on building the Expiration feature first. This feature allows listing all positions in the system whose expiration dates have passed, effectively identifying expired positions. However, as I proceeded, I realized that enforcing expiration rules required a validation system to ensure that all Options trades had expiration dates. The business rule states that:
- A Confirmation with
CONTRACTSas itsunit_typemust have an Expiration Date.
- A Confirmation with
SHARESas itsunit_typedoes not require an Expiration Date, and if provided, it is silently ignored.
As I worked on these features, my commit history became interspersed with changes related to both Validations and Expirations. Cleaning up my commit history required restructuring it so that all changes related to the Validation engine were grouped into a separate set of commits before introducing changes for the Expiration Date Rule. This restructuring ensures a more logical and maintainable commit history, making it easier to track the evolution of each feature.
2. Structured Approach to Validation
Validation occurs in three levels:
- Required Field Checks (ensuring necessary data is present)
- Domain Value Checks (ensuring data adheres to appropriate values and constraints)
- Business Rule Checks (enforcing logic specific to the application)
While cleaning up my commit history, I decided to separate validation logic into these distinct levels. I introduced Required Field Checks in one commit; next, I committed Domain Value Checks separately to keep the changes clear and modular. Finally, I committed Business Rule Checks, making sure that dependencies were properly handled and that the commit history showed a logical progression of validation enforcement.
When the Validation logic was turned on, several previously passing tests began to fail. These failures occurred because the tests contained Confirmation data for CONTRACTS but did not include an Expiration Date, which is now required by the new validation rules. I included the corrected tests in their own commit.
3. The Trade-Off Between Clean Code and Clean Commits
I knew I should have kept the various code changes isolated by feature as I was developing them. However, my attention span was very fragmented at the time. When I had a window I could spare for the project, I wanted to focus my mental capacity on writing clean code rather than on keeping a clean commit history. I have more mental bandwidth now for this project, that’s why I’m investing the time on this now.
This is what ChatGPT has to say about this:
This reinforces the importance of aligning development workflow with available cognitive resources–when time is limited, prioritizing functional correctness is reasonable, but when resources allow, commit hygiene becomes a valuable investment.
Oooh, I just learned a new phrase…“Commit hygiene”… I like it!
4. Commit History as a Roadmap
A well-structured commit history tells a story. In cleaning up the commit history, I split some commits and rearranged the files into other commits; I squashed other commits to maintain related changes together, and reorganized the order of commits which makes it easier to understand the true system requirements.
Competencies and Skills Used
- Test-Driven Development (TDD) — Incrementally introducing features while keeping tests passing at every step.
- Software Architecture Planning — Structuring feature implementation in a way that ensures smooth development flow.
- Dependency Management — Recognizing and addressing feature dependencies early in the development cycle.
- Version Control Best Practices — Maintaining a clean and structured commit history.
- Code Review Optimization — Writing commits that are easier to review and understand.
- Branching Strategies — Using feature branches and task branches to isolate concerns and keep changes organized.
Every iteration of Trendwatch continues to reinforce these lessons, helping me refine my workflow and approach to software development. As I move forward, I plan to further enhance my strategies for managing dependencies and structuring commits for maximum clarity and maintainability.
Stay tuned for more updates!