Early Progress

December 27, 2021

About one month has passed since the initial idea for this app came to me. I was able to write it down and create a repository for executing the idea fairly immediately. Since then I have spent no time on a UI for the app but some time working on backend code and an API for the UI to call. I have attempted to document some of my decisions because I know from experience, that when making infrequent visits to a code base, there is a fear of making changes when you can’t remember why things were done a certain way. The decisions I have documented are all available in the repository. It is probably not possible for me to document all decisions because there are certainly some that I am less aware that I am making. For example I have a preference for some ideas from Domain Driven Design, such as using a code-first approach to creating domain objects, rather than designing a schema or API endpoints first.

I also have a strong preference for keeping the code, documentation, build definitions, etc in the same place, so that a project is self contained. I believe (without much evidence) that this will help people remember to keep documentation up to date as they make changes to the project. At least I hope it will reduce the friction of such updates. One day I would like to play around with writing some tests that check that certain kinds of commits contain changes to the documentation too. I think it should be possible to do this and reduce the incidence of false positives in much the same way as the project ensures that commit messages are linted. In any case, I chose to make the repository for this project a monorepo that contains the documentation site, the API and the front-end app in a single repository, but I did not document this decision in the architecture decision records.

One final example of a decision that I have not really documented, is my personal preference for statically typed programming languages, or using optional type hints in dynamic languages. There is a great deal written on the topic of dynamic vs static type checking that everyone should read for themselves. My experience is that it is easier to find people who will do a good job of maintaining software if more rules are enforced for them, rather than left as optional disciplines. I include myself as one of these people as I could easily return to a project after sometime and forget what is expected of me. A prominent counterargument for dynamic typing over static typing is that test driven development (TDD) will prevent all the same problems that static typing manages to mitigate. My personal weakness is that I am not strong at TDD, and benefit a lot from static type checking, static analysis tools, etc. Further tests for certain conditions are likely to be necessary too. In my repository for the API I am using a tool to test that the GraphQL API I create has sufficient documentation included in the definition, to allow users of the API to use it without further definitions that are documented elsewhere. This is a sort of integration test. In my professional work I have written these kinds of tests to ensure that all forms in an application had the same footer. I provide these as examples of tests that I find useful that are not unit tests, nor are they checks that are typically available in out-of-the-box linting tools.

I have chosen to build the first versions of the backend APIs for this app using Python, a dynamically typed language, with optional type hints. It was recommended to me as easy to learn and that has definitely been the case. I have been quite productive and only suffered due to a small number of gotchas very, very early in the process, which I resolved by reading about Python list comprehensions. In fact I am able to be fairly competent in Python without taking a language tutorial at all. Occasionally I have a syntax or other fundamental question that I search and find immediate answers to in either the official documentation or on Stack Overflow. Progress has been fast enough that I hope that I will have a working prototype of the backend API completed by the next time I am ready to write a blog post.