<adam12>
rapha: I use yard in some projects and rdoc in others (sdoc is rdoc + merging).
<adam12>
rapha: I find yard docs a bit noisy, and sometimes the method docs are just the params and return value, making them anemic and of little value. Juniors seem to like seeing the types, and on some teams, I like to have doctags just to make people think of the shape of data they are passing around. It's more "in your face" if you have to document 15
<adam12>
parameters, causing you to question your design decisions.
<rapha>
hmm i like that as a management strategy
<rapha>
and yes, that's the first thing i noticed after having run yardoc
<adam12>
rapha: rdoc is love/hate for me. You use plain prose to document, then (in theory) rely on rbs to provide the signatures. Accessing help through `ri` is more convenient than `yri` personally, and if you're in a newer version of `irb`, then `help` will load `ri` for you. Nice for experimenting.
<adam12>
rdoc's out of box template for HTML rendering is lackluster.
<rapha>
so maybe rdoc is more for me here, especially since this is a colleague's project and there's zero comments in the sourcecode and i'm doing this to familiarize myself with it and give a hand to those who might come after me.
<adam12>
Yes, I'd just rdoc then, since it's part of stdlib.
<rapha>
but i never use "help" or "ri". i'd like to have an HTML page in a second window, please. rdoc does do that, too, right?
TrufflePump has joined #ruby
<rapha>
ah, yes, found it.
<rapha>
thanks for the horizon-widening input, adam12! :)
TrufflePump has quit [Ping timeout: 276 seconds]
<ox1eef>
my vote is +1 for yard.
<ox1eef>
especially if it is an exercise to understand the code, as you'd usually annotate such things as param "types", and return "types", and to do that you have to understand the code first.
danjo007 has quit [Quit: danjo007]
<ox1eef>
the default yard template is not perfect, but it is quite easy to extend or modify, without creating an entirely new template.
proportions has quit [Quit: ...]
<rapha>
hmm
danjo007 has joined #ruby
<ox1eef>
plus, it really goes beyond such params and return, there is a whole set of tags that are well suited to describing ruby code, especially that which is dynamic and otherwise hard to cover: https://www.rubydoc.info/gems/yard/file/docs/Tags.md
<rapha>
it was really quick to get that HTML page with Yard, true
<rapha>
maybe i'll work on my annotations for a few days and then regenerate and then revisit the question
<ox1eef>
best of luck with it :)
<rapha>
thanks :)
<rapha>
right now wondering about a warning produced by his code
TrufflePump has joined #ruby
<rapha>
there's a bunch of "::Importers += [::FooImporter]" which always causes "warning: already initialized constant Importers"
<rapha>
what does that even mean ... adding to ... a class itself?
<ox1eef>
should be << probably, += expands to Importers = Importers + FooImporter.
<rapha>
ah, it's defined first here: `-(::Importers||=Set.new).to_a.compact.sort_by(&:to_s).each do |importer_class|` (this being inside of HAML)
<rapha>
why would you use the :: prefix here?
<ox1eef>
that's used you want to reference a constant at the top-level, and there is another constant of the same name in the immediate scope which would be found first.
<ox1eef>
id check if that's even needed, it's usually not
<rapha>
he uses that pattern _every_where and for much much more specific names than this one ... i think it might be borne out of lazyness
<ox1eef>
yeah, or defensive coding
<rapha>
ah, that's an actual term? cool
<ox1eef>
yeah, it's not usually a good thing though
TrufflePump has quit [Ping timeout: 248 seconds]
<rapha>
defensive _driving_ is generally a good thing, unless, you're, say, being chased by a tornado ... ?
<ox1eef>
it depends. in this particular case i don't think it helps.
<ox1eef>
it's like coding "what if?" and trying to cover every little thing that could happen, but probably won't.
<ox1eef>
so it has its place, but i dont think this is one of them.
rvalue has quit [Read error: Connection reset by peer]
rvalue has joined #ruby
* rapha
makes a mental note to re-work that code a bit once he understands it better
spuz has quit [Quit: Client closed]
<rapha>
hmm, interesting
<rapha>
about the ::Importers||=Set.new I asked him if that couldn't just as well be an $Importers||=Set.new or whatever would be the needed scope, and he said, no, it "must be a constant inside of which a mutable object is stored". I have much learning to do.
<rapha>
but got permission to remove the [] and change += to << :)
danjo007 has quit [Quit: danjo007]
danjo007 has joined #ruby
<ox1eef>
$Importers is not a constant, but a global variable.
jpn has quit [Ping timeout: 246 seconds]
s-liao-2000 has joined #ruby
s-liao-2000 has quit [Client Quit]
jpn has joined #ruby
John_Ivan has joined #ruby
onyx has joined #ruby
<rapha>
yes I know
<rapha>
I just thought, why not use a global variable
<rapha>
But he says (for the reason cited above) that it must be a constant
<rapha>
Now what I'm wondering, is, why would you store a _mutable_ object inside a _constant_, which is, by definition, _im_mutable
TrufflePump has joined #ruby
<adam12>
I can't remember if there's a great reason for this, but a lot of people use a constant in place of a singleton.
<adam12>
ie, an alternative to the Singleton module.
<adam12>
I presume in some ways, they use the constant (and not a global) in favour of consistency. Re-assigning the constant causes warnings, where as the global does not.
<adam12>
MyConfig = Config.new vs $config = Config.new.
<ox1eef>
you're certainly right, but still: in general, global variables are frowned upon and you will rarely see them, even though a constant is quite similar and a global reference as well, sort of - BasicObject is the special case who has an empty constant lookup table.
s-liao-2000 has joined #ruby
<adam12>
I didn't want to really go down that road, because where are some valuable use cases of a global; ie. $stdout vs STDOUT
<adam12>
but you're right.
<ox1eef>
i agree, when i'm reassigning stdout i use $stdout and leave STDOUT for setting it back to its original value.
reset has joined #ruby
jpn has quit [Ping timeout: 260 seconds]
davidw has joined #ruby
<havenwood>
rapha: Yeah, shoveling is the right thing to do. A constant variable is SCREAMING_SNAKE_CASE by convention.
<havenwood>
You're right to avoid the warning from reassigning a constant.
<havenwood>
rapha: The constant is presumably within your namespace? Avoid defining your own globals. They're not namespaced and can stomp on each other.
<adam12>
That's another good reason.
favadi has joined #ruby
jpn has joined #ruby
favadi has quit [Quit: My MacBook has gone to sleep. ZZZzzz…]
jpn_ has joined #ruby
jpn has quit [Ping timeout: 256 seconds]
favadi has joined #ruby
donofrio_ has joined #ruby
donofrio has quit [Ping timeout: 248 seconds]
favadi has quit [Quit: My MacBook has gone to sleep. ZZZzzz…]
peder has quit [Ping timeout: 240 seconds]
desnudopenguino has quit [Quit: desnudopenguino]
Ziyan has joined #ruby
peder has joined #ruby
jpn has joined #ruby
jpn_ has quit [Ping timeout: 255 seconds]
dionysus69 has quit [Ping timeout: 240 seconds]
donofrio_ has quit [Ping timeout: 256 seconds]
donofrio has joined #ruby
yosafbridge has quit [Quit: Leaving]
hexology- has joined #ruby
hexology has quit [Quit: hex on you ...]
TrufflePump has joined #ruby
yosafbridge has joined #ruby
TrufflePump has quit [Ping timeout: 260 seconds]
jpn has quit [Ping timeout: 276 seconds]
<rapha>
Thanks for the explanations. Makes it a bit clearer what's going on.
<rapha>
What do you mean by "shoveling", thought, havenwood?
<adam12>
rapha: << is the shovel operator
<rapha>
havenwood: as for your question if it's within my namespace, I'm not not exactly sure because of the HAML.
<rapha>
Ah, ok
joto has joined #ruby
jpn has joined #ruby
<rapha>
Okay, so ::Importers is defined inside a HAML file which is called upon from within a call to get() inside the main script. And the same main script later loads the file that needs to shovel into ::Importers via instance_eval.
<rapha>
So, wait. Ur, yes, the constant is in my namespace wherever I may be, main script or HAML or eval'd script.
<ox1eef>
it can't be, ::Importers is defined at the top level, so it exists among every other constant at the top-level.
<ox1eef>
your own namespace would be something, Rapha::Importers
joto has quit [Ping timeout: 246 seconds]
<ox1eef>
something like,*
joto has joined #ruby
<rapha>
oooh
<rapha>
then i misunderstood the question
<rapha>
i read it as "is it in scope for you"
<ox1eef>
it's not so important, just avoid globals for now
<rapha>
ox1eef: i'm not writing my own code here, i'm trying to understand someone else's code. if i'm writing my own i'll use globals whenever i feel like doing so, but i also know i shouldn't. if you know the rules then you can break them :-)
<ox1eef>
that's fine, it is up to you at the end of the day but it is important to understand the implications.
<ox1eef>
they're bad for so many reasons, a long list, a book could be written about it.
<ox1eef>
break the rules of encapsulation, exist for as long as your process is running, name conflicts, terrible for threads - race condition waiting to happen, it goes on and on
<ox1eef>
if you want to design good software, avoid them, that would be my advice.
s-liao-2000 has quit [Quit: Client closed]
TrufflePump has joined #ruby
<rapha>
the thing is that i don't design software, i write scripts that do things and exit :)
<rapha>
if i were designing applications of some sort i'd be a better jedi here, and if i were desining libraries it'd be a wholly different thing again
<ox1eef>
yeah i sorta get it
<ox1eef>
fast and quick
<rapha>
:)
<rapha>
(which, let's be honest, usually really doesnt't need globals)
<ox1eef>
if you look at javascript for example, it has moved in a direction where apart from a few select globals on window, you can avoid them entirely, and the language makes that easy
dionysus69 has joined #ruby
<ox1eef>
you just cascade state through one function to the next.
_ht has joined #ruby
joto has quit [Ping timeout: 244 seconds]
dionysus69 has quit [Ping timeout: 246 seconds]
jpn has quit [Ping timeout: 246 seconds]
jpn has joined #ruby
TomyWork has quit [Remote host closed the connection]
<stackmystack>
Hello all. I've written a ruby extension for tree-sitter and I was wondering if I can find people here who would be kind enough to review/audit it.
<stackmystack>
Is this the right spot? Do you think I should post it somewhere else?
szkl has quit [Quit: Connection closed for inactivity]
cocalero has quit [Quit: Going offline, see ya! (www.adiirc.com)]
jpn has quit [Ping timeout: 248 seconds]
caleb has quit []
ur5us has joined #ruby
John_Ivan_ has quit [Quit: Leaving]
markong has joined #ruby
caleb has joined #ruby
<Al2O3>
anyway, neat little basic forth interpreter. I should run some tests through it, they are online tests published to see about the durability and functionality of variouis languages, or systems.
<Al2O3>
pretty cool that it is written in as small as 64 lines of ruby.
twosuns has quit [Quit: ...]
stackmystack has quit [Quit: Client closed]
jpn has joined #ruby
<Al2O3>
putting together a black raspberry 'brewer's best/vinters' concentrate (ya, it will taste 'burned' likely) for my GF. She likes that flavor of the day.
<caleb>
I could go for some black raspberry ice cream
desnudopenguino has joined #ruby
TrufflePump has quit [Ping timeout: 248 seconds]
TrufflePump has joined #ruby
dionysus69 has quit [Ping timeout: 258 seconds]
hitherehowareyou has joined #ruby
hitherehowareyou has quit [Remote host closed the connection]