[LRUG] Ruby world and documentation

Mark Burns markthedeveloper at gmail.com
Thu Nov 24 10:27:29 PST 2011


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>


More information about the Chat mailing list