Omniref (YC W15) Is Rap Genius for Code • Hacker News Board

Re: Omniref (YC W15) Is Rap Genius for Code

#21

Post by sbov » Thu, Jan 01, 2015, 1:46 AM UTC

grandalf wrote: post #17

This has been missing for a long time. 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.

Re: Omniref (YC W15) Is Rap Genius for Code

#22

Post by meghhv » Thu, Jan 01, 2015, 3:36 AM UTC

This seems like a great resource living within the overlap of Stack Overflow and Genius. What's the business model look like?

Re: Omniref (YC W15) Is Rap Genius for Code

#23

Post by timr » Thu, Jan 01, 2015, 4:44 AM UTC

grandalf wrote: post #18

suggestions: - 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…

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!)

Re: Omniref (YC W15) Is Rap Genius for Code

#24

Post by timr » Thu, Jan 01, 2015, 4:50 AM UTC

melling wrote: post #19

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: https://forums.handmadehero.org/index.php?option=com_content...

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.

Re: Omniref (YC W15) Is Rap Genius for Code

#25

Post by xasos » Thu, Jan 01, 2015, 5:10 AM UTC

_9hey wrote: post #15

The world needs a rap genius for scientific papers

I would love this. While I enjoy reading scientific papers, some are just over my head.

Re: Omniref (YC W15) Is Rap Genius for Code

#26

Post by cheng1 » Thu, Jan 01, 2015, 10:06 AM UTC

It's amazing that this seemingly small project got YC invested.

Is that because you have a great traffic? Or it's your background? Or they just love the idea and the demo?

Re: Omniref (YC W15) Is Rap Genius for Code

#27

Post by grandalf » Thu, Jan 01, 2015, 5:34 PM UTC

sbov wrote: post #21

grandalf wrote: post #17

This has been missing for a long time. 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 co…

I think for practical purposes there would ideally be a convention for the high level aspect of a commit message and the details...

Though the counter-argument is to commit exactly when a single reasonable commit message contains enough information... squashing defeats this.