News for hackers. Stuff that matters.

A comment on Document your code just by hitting “record”.

Re:Document your code just by hitting “record” by mgkimsal on Tuesday November 03, 2020 @06:13PM (#24985117)
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... ?
[ Parent | on HN ]
Re:Document your code just by hitting “record” by calcifer on Tuesday November 03, 2020 @06:41PM (#24985285)
> 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.

[ Parent | on HN ]
Re:Document your code just by hitting “record” by mgkimsal on Tuesday November 03, 2020 @07:06PM (#24985460)
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).
[ Parent | on HN ]
Re:Document your code just by hitting “record” by xmprt on Tuesday November 03, 2020 @07:10PM (#24985484)
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.
[ Parent | on HN ]
Re:Document your code just by hitting “record” by im3w1l on Tuesday November 03, 2020 @07:41PM (#24985666)
git blame can bring up relevant commits.
[ Parent | on HN ]
Re:Document your code just by hitting “record” by jefftk on Tuesday November 03, 2020 @06:17PM (#24985135)
> 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.

[ Parent | on HN ]
Re:Document your code just by hitting “record” by daotoad on Tuesday November 03, 2020 @09:46PM (#24986173)
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?

[ Parent | on HN ]
Re:Document your code just by hitting “record” by gitgud on Tuesday November 03, 2020 @07:06PM (#24985459)
Seems a bit redundant to store an audio file in version control which essentially represents a comment...

Why not just use a "speech-to-text" software to add documentation?

[ Parent | on HN ]
Re:Document your code just by hitting “record” by mgkimsal on Tuesday November 03, 2020 @10:32PM (#24986294)
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.

[ Parent | on HN ]
Re:Document your code just by hitting “record” by fmpwizard on Tuesday November 03, 2020 @08:50PM (#24985971)
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
[ Parent | on HN ]
Re:Document your code just by hitting “record” by mgkimsal on Thursday November 05, 2020 @10:33PM (#25004610)
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.

[ Parent | on HN ]
Re:Document your code just by hitting “record” by tomatohs on Tuesday November 03, 2020 @06:22PM (#24985171)
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.

https://github.com/haxordx/paircast-demo-1/blame/main/main.j...

[ Parent | on HN ]
Re:Document your code just by hitting “record” by dmcg on Wednesday November 04, 2020 @07:40AM (#24988459)
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.

[ Parent | on HN ]
Re:Document your code just by hitting “record” by tomatohs on Tuesday November 03, 2020 @06:24PM (#24985187)
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.
[ Parent | on HN ]
Re:Document your code just by hitting “record” by tomjakubowski on Tuesday November 03, 2020 @06:28PM (#24985200)
Given that the audio files don't need to change too often, is storing them in plain git an option?
[ Parent | on HN ]
Re:Document your code just by hitting “record” by tomatohs on Tuesday November 03, 2020 @06:44PM (#24985303)
Hadn't thought of storing only audio, that would definitely be possible, but doesn't seem very useful.
[ Parent | on HN ]
Re:Document your code just by hitting “record” by bausano_michael on Tuesday November 03, 2020 @06:22PM (#24985166)
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.

_EDIT: word order_

[ Parent | on HN ]
Re:Document your code just by hitting “record” by contravariant on Tuesday November 03, 2020 @07:04PM (#24985444)
There's bound to be some way to insert audio in an org-file at this point, surely?
[ Parent | on HN ]