a 6-7 months ago, as a side project (which I never got around to finishing) I was trying to build was something like this. Actually, when I pitched the idea to my friends, the line I used was "rap genius for code". (was trying to annotate huge open source projects like the linux kernel) So the second I saw this post the first words I said to myself were "fuck! I should have finished it".
But this is great!
What sorts of stuff do you guys have planned for indexing methods?
It looks like right now there's full text search which is already really useful. I'd be really interested to see some more structured search based on the AST of the code for example. Hoogle is a really good example of something similar for Haskell, admittedly that relies heavily on the strongly typed nature of Haskell and probably won't work for Ruby.
We do a lot of custom tokenizing, indexing and scoring logic right now to (for example) make method name searches work like you'd expect: you can (mostly) search for a common method name in activerecord, and the right thing will come up, as opposed to one of the many different forks. This is a constant game of whack-a-mole for us.
That said, we have more features planned than time to implement them...we've got a method-body search working internally, but we're not yet happy with the quality of the results. We'd definitely like to do something with signals coming from the AST to improve that. We also have signals in place to help rank based on usage across all the code we know about, but those could be a lot more robust. We're also going to be doing a pass in the near future to deal with some noisy results that have been leaking in since we opened up to all GitHub repositories.
We're open to suggestions, though...do you have an example of something you'd like to see us implement?
That is actually a good idea. One of the reasons I think the ACM Digital Library has failed to live up to its potential (besides being closed) is that they could do cool useful things like this and choose not to.
Part of the programmer culture appears (unfortunately) to include writing code and then thinking that explaining the thinking behind the code is beneath you.
This is evidenced by the very large percentage of open source releases where the first commit is a very polished codebase.
I agree - whys are very important. I try to document why I do certain things with comments.
That said, is there a such thing as a commit message too long? If I were to include the thinking behind code I would have some commit messages over 500 lines long.
Currently I just create an Evernote note for each change I make, which documents all the whys, the research, the issues, pros/cons, etc. with a given change. The commit message usually gets a much briefer version of it.
- allow authors to write a general overview (with links to methods) of the design philosophy, tradeoffs accepted, stuff that they would do differently now, etc. This could help generate smart pull requests for bigger / more significant features too.
- allow people to ask questions about a line of code.
- allow people to request/contribute better documentation, categorized as api docs, usage examples, etc.
- Allow the author to "accept" an annotation as literate comments submitted as a fork/pr via github.
- let users follow a method or class.
- let users generate a list of methods to follow in a library based on hot path analysis of library use (maybe I only use 3 methods and would love to see changes to those coming from upstream)
- let users contribute method rewrites or unit tests of individual methods as annotations.
- ideally dialogues would ensue about clever/clear ways to implement things. I'd enjoy reading those dialogues.
Wow, thanks for the feedback! Some specific responses:
"allow people to ask questions about a line of code."
we do this now! highlight a line of code, and you'll see a prompt.
"Allow the author to "accept" an annotation as literate comments submitted as a fork/pr via github."
That's a good idea. We'll need to work out the model (i.e. is it opt-in for the maintainer?) so that we don't irritate people with unsolicited requests, but I like it.
"let users follow a method or class."
This is coming soon! Following was naively implemented in the simplest way possible. We're expanding it now.
"let users generate a list of methods to follow in a library based on hot path analysis of library use"
Oh, that's interesting...will have to ponder it for a while....
If you have anything else, just shoot us an email: support@omniref.com. That goes to both of us, and we reply to just about everything we get (most of our current features came from direct user requests!)
Hope there will be a way to provide illustrations, diagrams, etc so people can better discuss the source at a higher level. The pics for HandMade Hero are nice:
Yep. We actually support image embeds right now, but we haven't set up our own image hosting yet. But if you post an imgur link or something using markdown, we'll show it as an image.
26 comments
[ 3.0 ms ] story [ 81.3 ms ] threada 6-7 months ago, as a side project (which I never got around to finishing) I was trying to build was something like this. Actually, when I pitched the idea to my friends, the line I used was "rap genius for code". (was trying to annotate huge open source projects like the linux kernel) So the second I saw this post the first words I said to myself were "fuck! I should have finished it". But this is great!
It looks like right now there's full text search which is already really useful. I'd be really interested to see some more structured search based on the AST of the code for example. Hoogle is a really good example of something similar for Haskell, admittedly that relies heavily on the strongly typed nature of Haskell and probably won't work for Ruby.
Very cool stuff guys.
That said, we have more features planned than time to implement them...we've got a method-body search working internally, but we're not yet happy with the quality of the results. We'd definitely like to do something with signals coming from the AST to improve that. We also have signals in place to help rank based on usage across all the code we know about, but those could be a lot more robust. We're also going to be doing a pass in the near future to deal with some noisy results that have been leaking in since we opened up to all GitHub repositories.
We're open to suggestions, though...do you have an example of something you'd like to see us implement?
Part of the programmer culture appears (unfortunately) to include writing code and then thinking that explaining the thinking behind the code is beneath you.
This is evidenced by the very large percentage of open source releases where the first commit is a very polished codebase.
That said, is there a such thing as a commit message too long? If I were to include the thinking behind code I would have some commit messages over 500 lines long.
Currently I just create an Evernote note for each change I make, which documents all the whys, the research, the issues, pros/cons, etc. with a given change. The commit message usually gets a much briefer version of it.
Though the counter-argument is to commit exactly when a single reasonable commit message contains enough information... squashing defeats this.
- allow authors to write a general overview (with links to methods) of the design philosophy, tradeoffs accepted, stuff that they would do differently now, etc. This could help generate smart pull requests for bigger / more significant features too.
- allow people to ask questions about a line of code.
- allow people to request/contribute better documentation, categorized as api docs, usage examples, etc.
- Allow the author to "accept" an annotation as literate comments submitted as a fork/pr via github.
- let users follow a method or class.
- let users generate a list of methods to follow in a library based on hot path analysis of library use (maybe I only use 3 methods and would love to see changes to those coming from upstream)
- let users contribute method rewrites or unit tests of individual methods as annotations.
- ideally dialogues would ensue about clever/clear ways to implement things. I'd enjoy reading those dialogues.
"allow people to ask questions about a line of code."
we do this now! highlight a line of code, and you'll see a prompt.
"Allow the author to "accept" an annotation as literate comments submitted as a fork/pr via github."
That's a good idea. We'll need to work out the model (i.e. is it opt-in for the maintainer?) so that we don't irritate people with unsolicited requests, but I like it.
"let users follow a method or class."
This is coming soon! Following was naively implemented in the simplest way possible. We're expanding it now.
"let users generate a list of methods to follow in a library based on hot path analysis of library use"
Oh, that's interesting...will have to ponder it for a while....
If you have anything else, just shoot us an email: support@omniref.com. That goes to both of us, and we reply to just about everything we get (most of our current features came from direct user requests!)
https://forums.handmadehero.org/index.php?option=com_content...
Is that because you have a great traffic? Or it's your background? Or they just love the idea and the demo?