I’m wondering how (and whether) people order notes on software they’re developing/updating (especially as ‘unofficial’ software engineers).
Some more context: I’m a hydrological engineer who recently started working on a new project. The goal is to add some new modules/update Python code that a colleague of mine originally co-developed and subsequently updated whenever it was the goal of a project. The software is in use at the government, but also contains a lot of deprecated code, so it’s a matter of finding my way through the forest to see where I can make the requested updates without destroying anything else (luckily, there’s git).
So far, I’ve resorted to making a note for each .py-file. Classes and functions defined within each file are denoted with headers, so I can make intra- and interfile links to specific classes and functions whenever necessary. By noting down the dependencies within each file (i.e. links to other .py-files), I get a feeling of the overall structure of the software package. So far, this has helped my in finding the locations in the code which I probably have to adapt, while simultaneously allowing for having the overview of the larger structure.
My first instinct is that these notes you’re making are actually what should live in the code files themselves in python doc strings. It sounds like you’re going through the exercise of writing technical documentation about the project, and if you’re doing that you might as well actually document for your colleges and your future self. If you’re describing what a function does in your .md note - it’s probably better to write that IN the function between a set of """
For jumping between functions and files so that you can make sense of what’s going on, is basically sounds like you’re reinventing an index of the program which many editors will handle for you already.
In some sense, you’re rewriting an existing program in an obsidian vault as .md file which seems like a bit of a waste. The py files are themselves just text files that are indexed by an IDE in a way not dissimilar from how obsidian indexes the md files, and it’s actually preferred that notes about the code live in the same file as the code.
1 Like
Those are some valid points, thanks! In general, it seems better not to do what is being done already in other programs.
Additionally, I’m actively trying to a) add docstrings and b) ensure that there is technical documentation.
However, for me personally Obsidian still has a place in the workflow, as it is relevant to link (on a high level) principles and theory (e.g. a type of model) with the package where it is implemented.