My personal take on documentation is that you should document public APIs <div>but make your code simple enough to read.</div><div><br></div><div>Normally if you find that you need to comment a piece of code in order for it to be understood</div>

<div>it is a ripe case for extract method, or introducing a new class because you've broken the SRP.</div><div>Another example, if you have a lot of conditions then it often means you need to utilise polymorphism.</div>

<div>There's so many examples and plenty of books been written about refactoring, so I could just go</div><div>on iterating various patterns that refer to design/code smells or assume you already know or can</div><div>

find good books on refactoring such as </div><div><br></div><div><a href="http://martinfowler.com/books.html#refactoringRubyEd">http://martinfowler.com/books.html#refactoringRubyEd</a></div><div><br></div><div>Often a simple name of what the code snippet does would replace the comment.</div>

<div>Making judicious use of methods rather than local variables with</div><div>||= style caching can really improve readability too.</div><div><br>There's rarely a case I've seen that a comment would be better than a refactor.</div>

<div>And if you're worried about performance from all these extra method calls, just don't.</div><div><br></div><div>You really can and should optimise later. Plus if you came from the C++ world to ruby world</div>

<div>you've probably not done it for performance reasons anyway.</div><div><br><div class="gmail_quote">On 24 November 2011 15:49, Peter Vrabel <span dir="ltr"><<a href="mailto:kybu@kybu.org">kybu@kybu.org</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div class="im"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">


The command 'gem server' might be what you're looking for, providing that<br>
when you installed the gems you have allowed them to compile RI and RDOC<br>
you get access to the documentation through a web interface,<br>
<br>
However the new hotness in documentation seems to be YARD,<br>
<a href="http://yardoc.org/" target="_blank">http://yardoc.org/</a> I haven't written a lot of documentation, but it seems<br>
that that's the way to go<br>
</blockquote>
<br></div>
Thanks for great hints!<br>
<br>
Cheers,<br>
  kybu<div class="HOEnZb"><div class="h5"><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
<br>
On 24/11/2011 15:07, "Peter Vrabel" <<a href="mailto:kybu@kybu.org" target="_blank">kybu@kybu.org</a>> wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hi guys,<br>
<br>
a bit of introduction at the beginning. I've got C++, Unix background,<br>
doing system level programming, but I'd been using Ruby to create various<br>
<br>
internal tools, but I never got deeper into it, until recently. I'm just<br>
finishing the first milestone doing remote API for a web community<br>
portal.<br>
I use Zeromq and Google Protocol Buffers to scale it well (with bunch of<br>
other gems, like Sinatra, rest-client, ...). I've learnt a lot about Ruby<br>
<br>
during this, getting into using it idiomatically and I really like it.<br>
<br>
My observation and question is about libraries/gems documentation. I'm<br>
finding myself quite often reading gems code just to understand, how can<br>
I<br>
use it. Mostly, they've got s simple introduction in README and then<br>
you're on your own. But I am used to having a comprehensive reference<br>
documentation/manual, as that's what you've got in C++, Unix world. You<br>
can read about 'corner cases' which would otherwise slip by your<br>
attention. For example that you can get value 60, sometime 61 for seconds<br>
<br>
when getting current timestamp. So called 'leap seconds'. In Ruby,<br>
documentation seems to me 'more shallow'. Please, don't get me wrong, I'm<br>
<br>
not saying it's bad. It probably comes with the fact, that Ruby is easy<br>
to<br>
pick up and just to do your work. I definitely learn when reading others<br>
code (obviously ;). I would just like to hear what other folks think<br>
about<br>
it and go about it. And is there any handy application that show, search<br>
installed gems documentation apart from a command line 'ri'?<br>
<br>
Thanks a lot.<br>
<br>
Cheers,<br>
  kybu<br>
______________________________<u></u>_________________<br>
Chat mailing list<br>
<a href="mailto:Chat@lists.lrug.org" target="_blank">Chat@lists.lrug.org</a><br>
<a href="http://lists.lrug.org/listinfo.cgi/chat-lrug.org" target="_blank">http://lists.lrug.org/<u></u>listinfo.cgi/chat-lrug.org</a><br>
</blockquote>
<br>
______________________________<u></u>_________________<br>
Chat mailing list<br>
<a href="mailto:Chat@lists.lrug.org" target="_blank">Chat@lists.lrug.org</a><br>
<a href="http://lists.lrug.org/listinfo.cgi/chat-lrug.org" target="_blank">http://lists.lrug.org/<u></u>listinfo.cgi/chat-lrug.org</a><br>
</blockquote>
______________________________<u></u>_________________<br>
Chat mailing list<br>
<a href="mailto:Chat@lists.lrug.org" target="_blank">Chat@lists.lrug.org</a><br>
<a href="http://lists.lrug.org/listinfo.cgi/chat-lrug.org" target="_blank">http://lists.lrug.org/<u></u>listinfo.cgi/chat-lrug.org</a><br>
</div></div></blockquote></div><br></div>