about.... 15 years ago, I had an idea for allowing embedding of multimedia files with commits. svn was the thing at the time, and eclipse and netbeans were the dominant players. I had 0 idea about how to build something like that, but it seemed useful. still does. even now, we end up, sometimes, writing comments in pull requests which may correspond to particular lines in particular files, but we can't easily connect anything else. Perhaps some metadata format for comments could be defined and IDE plugins could make fetch the media... ?
OFTEN I want some form of "stream of consciousness" thoughts associated with code - "spoke with Titus and Jen about this, and the loop needs to be broken up because foobar...". most of the time if I embed comments like that, someone blocks a PR or just rips them out in the name of "cleanliness", then 3 years later people are wondering "why was this done this way?" Links to tickets can help, but ... ticket trackers change - a reference to Trello card GKO-826 does no good when the project moved off Trello 2 years ago.
Perhaps long term there's no good way to deal with any of this...?
// @medianote ./20180902121352.mp3
while (x<users.length) {
// ...
}
button in IDE to record audio note, and have it stored under ./.media relative folder... ?
> thoughts associated with code - "spoke with Titus and Jen about this, and the loop needs to be broken up because foobar...". most of the time if I embed comments like that, someone blocks a PR or just rips them out in the name of "cleanliness", then 3 years later people are wondering "why was this done this way?"
I really hate it when people do this. The commit message should be all about the why (the diff already tells me the what), getting rid of it means removing the only useful bit of info from the commit message.
There's code comments and commit messages. I was referring to code comments, not messages. I am on some projects where others are really strict about "no superfluous comments". Yet... the thing that's helped most when looking at 5-10 year old code is someone's multi-line comment about what decision led to something (sometimes with decision maker names, dates, etc) and some reasoning. None of that is remotely discoverable in things like confluence (at least in any project I've worked on in the last 10 years or so).
It's crazy that businesses that are built on top of code spend hours in meetings to come to a decision that isn't documented anywhere for people to see 2 years down the line. These are team leads who have worked for close to a decade. They must realize the value in documentation by this point.
> Links to tickets can help, but ... ticket trackers change - a reference to Trello card GKO-826 does no good when the project moved off Trello 2 years ago.
Keeping links working within your organization is really important, and I wish places prioritized it more. Our code often links to our bug tracker, and I'm thankful that my current employer does value this and these links work even when they are decades old.
This is why I keep coming back to the idea that we need tools that keep their data serialized in the repo itself. I talking about issue tracking, project planning, documentation like github wikis or confluence, all that stuff.
There are quite a few problems to solve to support this that I haven't worked out properly, otherwise I'd be building it.
For example, where do you keep your backlog? How do issues and issue statuses get stored? How do you report on open tickets and progress if the state is scattered across a bunch of different branches?
maybe. I used audio as an example, and it was on my mind years ago when screen capture was far less common. Audio/screenshots/movies - Webex snippets, etc.
Also, sometimes audio can let you more easily capture nuance/tone that you don't get in text alone. And ... some people just are good at talking through their thought process.
That's an awful reason to block a PR. I've been doing code review for the past 6+ years and I'm on the other side, I often ask for better, and longer code comments, for the reason you highlighted, 5 years later (or even months later) that long comment will save us hours
You're in the minority of people I've worked with in the last few years who make those sorts of decisions.
When I can, I try to keep some parallel /docs files with some relatively up to date tech notes close to the code. Jira/confluence/etc might also have info, but the docs that are connected in the same repo have a different level of usefulness for some things.
This is actually one of the more advanced features.
Since Paircast works with git, we can link each LOC to the point in the video where it was created. Take a look at the `git blame` and the Paircast links in the sidebar.
In the same timescales I was thinking the same thing, but in particular recording the conversation between pair programmers.
OneNote had (has?) a mode where you could click on sections of a meeting note and hear the audio from the time the text was written.
Extend that to an IDE and every time you found yourself saying “what were they thinking when they wrote this?” you could listen in on the conversation and find out.
I would have loved to store the media within the git repo that Paircast creates, but unfortunately that requires `git-lfs` which developers absolutely hate.
I've been playing around in my head with tangential feature. I run into situations where I must make some assumptions about a codebase and its context which aren't translated into the type system. I add comments to remind readers whenever I feel like an assumption should be stressed.
However assumptions change with time. I'd like to be able to cross reference all the places in the code base where certain assumption was made to a readme section with necessary details and background. In my ideal world IDE would resolve these links and made them easier to maintain.
OFTEN I want some form of "stream of consciousness" thoughts associated with code - "spoke with Titus and Jen about this, and the loop needs to be broken up because foobar...". most of the time if I embed comments like that, someone blocks a PR or just rips them out in the name of "cleanliness", then 3 years later people are wondering "why was this done this way?" Links to tickets can help, but ... ticket trackers change - a reference to Trello card GKO-826 does no good when the project moved off Trello 2 years ago.
Perhaps long term there's no good way to deal with any of this...?
button in IDE to record audio note, and have it stored under ./.media relative folder... ?