[LRUG] Ruby world and documentation

[Mark Burns]

My personal take on documentation is that you should document public APIs
but make your code simple enough to read.

Normally if you find that you need to comment a piece of code in order for
it to be understood
it is a ripe case for extract method, or introducing a new class because
you've broken the SRP.
Another example, if you have a lot of conditions then it often means you
need to utilise polymorphism.
There's so many examples and plenty of books been written about
refactoring, so I could just go
on iterating various patterns that refer to design/code smells or assume
you already know or can
find good books on refactoring such as

http://martinfowler.com/books.html#refactoringRubyEd

Often a simple name of what the code snippet does would replace the comment.
Making judicious use of methods rather than local variables with
||= style caching can really improve readability too.

There's rarely a case I've seen that a comment would be better than a
refactor.
And if you're worried about performance from all these extra method calls,
just don't.

You really can and should optimise later. Plus if you came from the C++
world to ruby world
you've probably not done it for performance reasons anyway.

On 24 November 2011 15:49, Peter Vrabel <kybu at kybu.org> wrote:

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