6 ms·

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!

achou 6y ago
How do CodeTours handle drift as the code base changes?
- kissgyorgy 6y ago
  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 https://github.com/microsoft/codetour#versioning-tours
  - qbasic_forever 6y ago
    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.
    - lostintangent 6y ago
      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.
    - pythonaut_16 6y ago
      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.
- rmorey 6y ago
  They have a GitHub Action to monitor this: https://github.com/marketplace/actions/codetour-watch https://github.com/marketplace/actions/codetour-watch
ldayley 6y ago
This is fantastic! Is this an official Microsoft supported plugin?
- lostintangent 6y ago
  Yep! It originally started as a personal "hack" project, but it's now being officially supported.
the_duke 6y ago
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/ https://tree-sitter.github.io/tree-sitter/
- qbasic_forever 6y ago
  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 6y ago
    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 6y ago
    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!
    - 6y ago
eddyg 6y ago
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 6y ago
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.
blondin 6y ago
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 6y ago
I'm curious, if code has been updated, how we should update CodeTour?
pineconewarrior 6y ago
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.
super_linear 6y ago
Sorry for the naive question but how is user privacy handled? Is data about the repo sent externally? I assume this would primarily be useful for OSS projects and not private or internal/confidential projects?
- lostintangent 6y ago
  Hey! When you record a tour, it simply creates a JSON file that can be committed/maintained as part of the associated codebase. Then, when someone takes the tour later, they're simply "reading" that file locally in their editor, and so no data about the codebase is ever sent externally.
  - super_linear 6y ago
    Thanks so for the clarification! That's great, I'm looking forward to using the tool.

achou 6y ago

How do CodeTours handle drift as the code base changes?

kissgyorgy 6y ago
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 https://github.com/microsoft/codetour#versioning-tours
- qbasic_forever 6y ago
  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.
  - lostintangent 6y ago
    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.
  - pythonaut_16 6y ago
    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.
rmorey 6y ago
They have a GitHub Action to monitor this: https://github.com/marketplace/actions/codetour-watch https://github.com/marketplace/actions/codetour-watch

ldayley 6y ago

This is fantastic! Is this an official Microsoft supported plugin?

lostintangent 6y ago
Yep! It originally started as a personal "hack" project, but it's now being officially supported.

the_duke 6y ago

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/ https://tree-sitter.github.io/tree-sitter/

qbasic_forever 6y ago
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 6y ago
  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 6y ago
  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!
  - 6y ago

eddyg 6y ago

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 6y ago

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.

blondin 6y ago

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 6y ago

I'm curious, if code has been updated, how we should update CodeTour?

pineconewarrior 6y ago

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.

super_linear 6y ago

Sorry for the naive question but how is user privacy handled? Is data about the repo sent externally? I assume this would primarily be useful for OSS projects and not private or internal/confidential projects?

lostintangent 6y ago
Hey! When you record a tour, it simply creates a JSON file that can be committed/maintained as part of the associated codebase. Then, when someone takes the tour later, they're simply "reading" that file locally in their editor, and so no data about the codebase is ever sent externally.
- super_linear 6y ago
  Thanks so for the clarification! That's great, I'm looking forward to using the tool.