+972 52-548-6969
Ohloh stats: RavenDB
time to read 1 min | 94 words
That is quite nice to see:
One of the worries that some people has about RavenDB is that they consider it to be a sole developer effort. I wanted to make sure that everyone understood that this isn’t the case.
RavenDB has quite a big community (over 50 people have contributed code over the lifetime of the project, and has a company and a development behind it.
Comments
Wow.
FYI. The link to ohloh is broken.
Thanks, fixed
"Few source code comments
Raven DB is written mostly in C#.
Across all C# projects on Ohloh, 22% of all source code lines are comments. For Raven DB, this figure is only 15%.
This lack of comments puts Raven DB among the lowest one-third of all C# projects on Ohloh.
A high number of comments might indicate that the code is well-documented and organized, and could be a sign of a helpful and disciplined development team."
Really? Comments == disciplined development team?
Interesting, but how about licensing? RavenDB is open source but you provide both GPL and commercial - this means that all who contributes code to RavenDB must agree that you sell their code too, are them ok with that? do they sign any special agreement about that? Do people who contributes to RavenDB get any discount to commercial license?
Many comments are often a sign of unreadable code.
Unfortunately, if you look up the Ohloh stats on Rhino Mocks, Rhino Queues, and Rhino ETL, the story isn't quite as good. Commit-wise, a couple look like abandon-ware. I wonder if that's the difference between maturity of product, size of product, number of users/interest level, or the fact that RavenDB is commercially sold and profitable? Hopefully RavenDB gains enough traction to be sustainable at these levels long-term.
Pavel, In order to get code included in ravendb, you sign a contributed license agreement
Jonty, I'll note that most comment count in C# is usually XML comments, which don't add a lot of value
Matt, I learned a LOT about how to run a project from those, and I've applied those lessons when building ravendb. It shows in the number of commuters, the community and the software itself
"I'll note that most comment count in C# is usually XML comments, which don't add a lot of value"
I understand that we need to name classes, properties, methods, etc. to be as self documenting as possible, but the fact the the XML comments are the basis for the Intellisense feature we know and love (I have yet to meet a dev who didn't, aside from SSMS but that's a different story) I fail to see how they do not add a lot of value. You can also, if you choose, use them to build MSDN like documentation with SandCastle.
Jedak, The problem with XML comments is that a lot of time, they don't add a lot of value. Typical example, interfaces have XML comments, but you get warnings if you don't add XML comments to the method impl, which is basically the same as the interface comments.
Jedak, The problem with XML comments is that a lot of time, they don't add a lot of value. Typical example, interfaces have XML comments, but you get warnings if you don't add XML comments to the method impl, which is basically the same as the interface comments.
Ayende, GhostDoc can be a great help to automagically copy the interface comments to the implementor class :-) But I agress that those are not giving value, just helping to spit out intellisense info and generate a help file.
C'mon. You get intellisense without xml comments too. Just name the method parameters well.
In my company somebody even started talking about code being rejected unless 30% of it were comments! Luckily they forgot about it fast.
Attila, That is sort of my point, is those things were generated by a tool, they aren't really that useful, are they?
I agree that most comments (especially ones generated by tools) don't add value. That's because most projects and devs fail at writing comments. Look at MSDN and how it documents .Net API, it has use cases, code examples, notes on usage (sometimes warnings of common mistakes). If Raven had the doc quality MSDN offers for .Net, I don't think I would ever have to look anywhere for assistance or bug people on forums or mailing lists (and waste time doing nothing until someone replies).
Alexei, Um, you do realize that you are offering a logical fallacy, right?
Yes it appears that there are plenty of forums, mailing lists and "bugging people for help" on a lot of the topics covered in MSDN.
Beside, walk just a bit off the beaten bath and you get very strange results.
For example: http://msdn.microsoft.com/en-us/library/bb351418(v=vs.90).aspx
If you don't know what a proper subset is, you won't be able to make heads or tails out of this.
@Ayende - you miss Alexei's point entirely - actually you dont - you're just ignoring it. No comments in code is just plain dumb and waste people's time when they need to know something. Oh well, you should have thought about that before you wrote 50K code lines as it's way too late now. Anyone who want to buy you out will think twice too. As usual, your arrogance gets in the way of your brain.
Ayende, your example is ridiculous in the extreme. If you don't know anything about set theory (including basic set definitions) you can't expect API doc to teach you mathematics. You've got no one but yourself to blame if you try to use set operations without know what sets are. Again, it's not MSDN's job to teach you basic math (and it is basic math).
Having said that, MSDN is not flawless, but at least it tries. Raven doesn't even make the most basic attempt. The only source of reliable info are the tutorials, and tutorials only teach people how to do the thing in the tutorial. A job of a good API doc is to define the API and all its capabilities to the user, a job of API doc is to teach the user about the API (which your MSDN example, does excellently, it even explains the corner cases).
Considering how much smaller public API of Raven is compared to whole .Net and Windows API that MSDN covers (and it's only the public API that you really need thorough treatment to, everything else is for devs only, and they can decide how much or how little docs they want), you don't really get to have an excuse of it being hard and you can't really point at the occasional errors in MSDN and say "Look, MSDN isn't 100% flawless, why bother with any of it?" Especilly not by pointing at 100% flawless doc page.
Joe, Have you looked at the RavenDB codebase? If not, you might want to take a peek before spouting off.
Alexei, a) What I know about sets, I learned in Hebrew, the terms and definitions are quite different. b) I guess you missed http://ravendb.net/documentation
Ayende,
a) so? b) That's my point, that whole page is an exercise in failure. It almost never even uses C#. Provides almost no working examples (the few times it does C# almost always assumes some mythical set up steps). That's why I said tutorials are the only way to learn anything about Raven, and those a few and far between.
@Ayende - yes I have looked at the code base - which is WHY I made my statement. As usual, your attempts to comment code are pathetic.
Just to clarify my main gripe is with ravendb.net/documentation page. Almost all of it is written by a designer of RavenDV for other designers of RavenDB. Most of it is concerned with how things are implemented internally. Users don't care how things are implemented or what internal representations of data are, users want to know how to use things. We see C# API, we want to know how to use it correctly and effectively. I for one do not wish to be guessing about intended use cases from design docs filled with HTTP captures and JSON layout samples.
Comment preview