From: "s.ross" Date: 2008-02-16T13:46:58+09:00 Subject: Re: Proper way to RDoc markup? not quite Readability is in the eye of the beholder. To me, good inline documentation is far more useful than long preambles because it's right next to (or on top of) the relevant code. Classes and methods that are prefaced by a ton of documentation feel like PHPDoc to me. I'll have to agree with Gary on this one but not just because of LOC -- because the proximity of the documentation to the code makes it more relevant. It also makes it more likely that I'll change the comment if I change the code. -s On Feb 15, 2008, at 8:17 PM, Jeremy McAnally wrote: > I'd rather have really readable code and good generated documentation > than 5 LOC. > > Of course, doing this often would throw off your app LOC to testing > LOC, now wouldn't it? ;) > > --Jeremy > > On Feb 15, 2008 5:42 PM, Gary Wright wrote: >> >> On Feb 15, 2008, at 5:28 PM, Jeremy McAnally wrote: >> >>> I guess...? You just need to pay attention to what you're doing. :P >>> I personally think this is more readable than inlining: >>> >>> # This does something fun >>> attr_reader :fun >>> >>> # This does something writable >>> attr_accessor :read_write >>> >>> # This does something AWESOME >>> attr_accessor :forty_two >> >> Yuck, that is 8 lines vs. 3 (below). I always found it >> strange that RDOC didn't parse comments to the right >> of an accessor declaration yet that is exactly how >> attributes are documented in the HTML pages generated >> by RDOC. >> >> attr_reader :fun # This does something fun >> attr_accessor :read_write # This does something writable >> attr_accessor :forty_two # This does something AWESOME >> >> >> Gary Wright >> >> > > > > -- > http://jeremymcanally.com/ > http://entp.com > > Read my books: > Ruby in Practice (http://manning.com/mcanally/) > My free Ruby e-book (http://humblelittlerubybook.com/) > > Or, my blogs: > http://mrneighborly.com > http://rubyinpractice.com >