[HN Gopher] CodeTour: VS Code extension to record and play guide...
___________________________________________________________________
CodeTour: VS Code extension to record and play guided walkthroughs
of codebases
Author : eddyg
Score : 266 points
Date : 2021-03-17 09:35 UTC (2 days ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| devanl wrote:
| I really like the idea of CodeTour, but unfortunately I'm the
| only person at the office that uses VS Code.
|
| I'm hoping that some day it'll be possible for my coworkers to
| follow a CodeTour without installing VS Code.
|
| Either when GitHub Codespaces reaches general availability or if
| I ever find the time and motivation to learn enough about
| github1s [1] and CodeTour to integrate the two.
|
| 1: https://github.com/conwnet/github1s
| zetaben wrote:
| That's exactly the issue we had at the office. So someone in
| our team built https://github.com/doctolib/code-tours-github we
| use it to help new joiners get into the codebase!
|
| Nota: It was previously pushed on HN (without to much success):
| https://news.ycombinator.com/item?id=25823697
| lostintangent wrote:
| You are my total hero for building this! Please let me know
| if there's anything you need from CodeTour in order to
| improve this experience :D
| zetaben wrote:
| Thanks! Sharing the love with the team. I'm sure they will
| be thrilled, and will probably reach out ;)
|
| The VS Code extension is also very much appreciated here so
| congrats again for the awesome tool!
| jerrygoyal wrote:
| I see one more opportunity for this.. to use in programming
| courses when sharing code with students.
| kissgyorgy wrote:
| Now we just need a repository for CodeTour recordings for open
| source projects! Really cool project, congrats!
| lostintangent wrote:
| Great idea! I've been thinking about creating a repo that could
| store tours for other repos. That way, the community could
| contribute them, without needing to check them into the target
| repo itself. Similar-ish to the definitelytyped ecosystem that
| TypeScript built up
| [deleted]
| winkelwagen wrote:
| Love this project. We've used it in a few repositories. The
| feedback from new hires was positive! Can recommend giving it a
| try
| lostintangent wrote:
| This is so awesome to hear! Thanks for sharing that feedback :D
| artur_makly wrote:
| brilliant idea. the only challenge is.. constant changes.
| oolonthegreat wrote:
| exciting project!
| gravyboat wrote:
| This is a fantastic idea. The concept of code tours is something
| I've been trying to push for via thorough readmes combined with
| example PRs to show users how to actually do something but this
| takes it to another level that I'm very happy to see.
| glenngillen wrote:
| CodeLingo's playbooks are an approach to solve that type of
| problem https://playbooks.codelingo.io/p
| arduinomancer wrote:
| This seems really cool but my immediate thought is that it might
| be pretty fragile compared to just screen recording.
| dariusj18 wrote:
| Create the tour, then screen record playing through it. Two
| birds one stone.
| arduinomancer wrote:
| That is true, could always screen record as a backup
|
| Or just have the user check out a specific commit
| lostintangent wrote:
| Hey! Thanks for posting this :) I'm the author/maintainer of
| CodeTour, and so I'd love to help answer any questions or
| thoughts about it!
| pineconewarrior wrote:
| What are the chances of this being ported to Jetbrains IDEs?
|
| Thank you for your hard work! I use both at work, so I'll still
| get some use out of this I'm sure.
| eddyg wrote:
| You're very welcome. It's a fantastic tool and well deserving
| of some coverage. Glad others here on HN saw fit to give it
| some upvotes!
| methyl wrote:
| I tried to record one, and after it was done it seems order was
| messed up - some steps from beginning were pushed to the end.
| Not sure if I can reproduce, but thought you might find it
| useful to know.
| achou wrote:
| How do CodeTours handle drift as the code base changes?
| rmorey wrote:
| They have a GitHub Action to monitor this:
| https://github.com/marketplace/actions/codetour-watch
| kissgyorgy wrote:
| without CodeTour needing to do anything about it, you can
| just use git and name CodeTour based on git tag, hash or
| something.
|
| Edit: It actually can reference a git ref, WOW:
| https://github.com/microsoft/codetour#versioning-tours
| qbasic_forever wrote:
| That doesn't really answer the question posed though--how
| does a tour stay up to date as code is changed? Does
| someone have to go in constantly and keep it up to date,
| pointing at the right spots, etc? It sounds like an
| incredible burden without dedicated staff or time to
| maintain--i.e. this is fine for projects established enough
| to have technical writers, evangelists, etc. but for 99% of
| projects it's just more burden and burnout. It's not really
| something you can farm out to your community or first time
| contributors either as deep analysis and understanding of a
| codebase takes real time and effort from the core devs.
| pythonaut_16 wrote:
| Pointing to git refs should be sufficient for code that's
| not super volatile.
|
| I personally envision using it for onboarding new
| developers to a code base, in which case I think being on
| an older ref should be fine, since I'm just trying to
| show the general structure of a project.
|
| I could also see using it in a code review context, in
| which case pointing it at the branch would also be fine.
|
| Also, if you look at the schema it generates for a tour,
| it would be pretty easy to go through and update the line
| numbers directly in the JSON.
| lostintangent wrote:
| I originally added the Git ref solution, as a simple way
| to enable "resilient playback" for some scenarios. In
| practice, that seems to work pretty well for many folks.
| But I agree that this isn't a full solution to the
| problem of code churn. I'm working on an enhancement
| right now, that will attach the steps to code in a more
| robust way.
|
| In general, I've seen a pretty great reaction from folks
| about the concept of CodeTour, and so I'm very focused on
| making them maintainable, since I believe that's the "big
| rock" needed to make them a worthy investment for more
| teams.
| ldayley wrote:
| This is fantastic! Is this an official Microsoft supported
| plugin?
| lostintangent wrote:
| Yep! It originally started as a personal "hack" project, but
| it's now being officially supported.
| the_duke wrote:
| A killer feature would be doing semantic analysis to attach
| steps to AST nodes instead of lines.
|
| EG a class or function.
|
| Without this it seems tours could be broken/outdated very
| quickly in active code bases.
|
| Do you have any plans for that?
|
| tree-sitter [1] supports parsing a lot of languages and could
| be a good way to make that happen without too much effort. (as
| long as items stay in the same file)
|
| [1] https://tree-sitter.github.io/tree-sitter/
| lostintangent wrote:
| I'm exploring this exact thing right now! I'm hoping to have
| something out in the next couple of weeks.
| qbasic_forever wrote:
| Or IMHO this is much better solved with a literate
| programming approach where the tour content lives inside the
| code as comments. Then as code is refactored and changed it's
| very obvious that the related docs and tour data has to
| change too.
| the_duke wrote:
| Agreed.
|
| But many developers might be very much against littering
| code with such tour comments, and be very much opposed to
| any kind of responsibility of updating tours during
| refactoring.
|
| Me included.
| lostintangent wrote:
| With CodeTour, you can have "content only steps"
| (introductories, interstitials), steps that speak to
| directories, and also, add steps to files that don't
| necessarily support comments (e.g. JSON). So there seemed
| to be some value in having the tour be more flexible, than
| what what might be achievable code comments alone.
|
| Additionally, after speaking with a bunch of folks, there
| are definitely teams that weren't interested in "polutting"
| their code with comments that might be tailored to
| onboarding new team members, and therefore, didn't need to
| be always visible.
|
| That said, I totally agree with the value of a literate
| programming-based solution. But there may also be some nice
| properties to a "side car" file as well, and so I'm
| primarily trying to explore how well we could make that
| work, in a resilient and easy-to-maintain way. We'll see
| how it goes!
| stareatgoats wrote:
| > there are definitely teams that weren't interested in
| "polutting" their code with comments
|
| Add an extension feature that toggles (hides/shows) those
| comments maybe?
| methyl wrote:
| Not an equivalent of literate programming. Here you can
| jump to arbitrary files at arbitrary points, in literate
| programming your code must flow from top to bottom
| linearly, which is most of the times impossible to achieve.
| qbasic_forever wrote:
| No not with Knuth's original ideas for literate
| programming and cweb. There's an explicit abstraction
| between the location of prose and the final source code
| output and they can be woven in any way the author
| desires. You can even insert intermediate steps, like
| pseudocode that show building up the architecture in
| small incomplete steps, and all of that is removed
| entirely from the final source code result. It is
| actually quite complex and why more modern literate
| programming systems ditch it and basically turn into
| fancier comments.
| methyl wrote:
| Sure, I get your point, but this description stands in
| opposite to previous statement that "tour content lives
| inside the code as comments".
|
| It seems to me that CodeTour is very close to Knuth's
| idea.
| qbasic_forever wrote:
| I recommend reading up on cweb and its history. The
| tangling and weaving metadata and prose lives in the code
| with special fenced blocks. Noweb is a modern version of
| it: https://github.com/nrnrnr/noweb (but it's not really
| used or maintained much anymore)
| blondin wrote:
| oh wow, what an amazing concept! i hope to see it evolve beyond
| vs code, like the language server concept.
|
| the first thing that came to mind are walkthroughs by original
| authors. in fact, i recently downloaded the source code for the
| first IRC server/client by the creator of the protocol. i could
| use a walkthrough. the c code is quite old and nothing online
| helps you understand it.
|
| this could help explain old code bases like the first unixes or
| the first c compilers. or maybe we can get id software people
| to do walkthroughs for doom, quake, etc.
|
| this is awesome.
| billconan wrote:
| I'm curious, if code has been updated, how we should update
| CodeTour?
| pama wrote:
| This sounds very useful. Does anyone know of any package similar
| to this for emacs?
| ashneo76 wrote:
| Yes. I would use this in emacs too. I don't do vscode. This can
| be done in emacs.
|
| Either way, great product and implementation.
___________________________________________________________________
(page generated 2021-03-19 23:00 UTC)