Ask HN: How do you keep track of the architecture of a personal project? | Hacker News Reader

Ask HN: How do you keep track of the architecture of a personal project?

15 pointscuriousgal7 comments

Hi HN,

I am working on a personal project in Python. Nothing fancy just some scientific calculation. I know that academics get flak for writing shitty code but I decided to use OOP as some of my models have a similar structure. For instance (no pun intended), I would create a global model class and each model would inherit from it and implement its own methods for calculation. Then I just parralelize the call to my super class.

The problem is, it's getting complicated as I need to keep track of the different classes and interactions. Should I look into UML? I am just curious how you guys keep track and document your software architecture when there's no spec sheet coming from above.

Thanks

View on HN

Depending on where you are in the project I would encourage something between...

* Rule of 3 - try applying whatever you're thinking of doing to 3 cases before giving in to the temptation to architect / consolidate.

* Architect w/ UML class diagrams + sequence diagrams of core interactions.

Someone mentioned architecture decision records, which are a great way to connect the first point to the second with a narrative!

https://en.m.wikipedia.org/wiki/Rule_of_three_(computer_prog...

[1] Draw.io is a very good tool to document architecture. Keep it simple.

[2] code2flow is also great to show high level logic.

README's in the repository are great to track changes in architecture with the code.

Easily understood architecture allows for easily understood code, which allows people to help you!

[1] https://draw.io

[2] https://code2flow.com

https://adr.github.io/ is about recording architecture decisions.

For visualizing it, try out the c4 model: https://c4model.com/

OT: If you feel things are really getting complex already, do ponder over whether there is scope for you to simplify things. Simplifying architecture is IMO more valuable than representing complex architecture, even if it is done using the best available tool.

UML helps. Recording design decisions and how classes are meant to be called/used is generally good reference for a rainy day in the future.

Since you are using Python, ensure you sufficiently document classes' purpose/responsibility in docstrings. Ensure the most important pieces of info stay close to the code where they are implemented.

Blog about it. It makes you think about the project from a different view.

Might be worthwhile to also check out https://plantuml.com/

I just keep lists that explain what each function does in my notes, for UML Lucidchart has some templates.

Reply on news.ycombinator.com