

Reading the Puppet Source - Or, How I Lost My Sanity - zdw
http://somethingsinistral.net/blog/reading-the-puppet-source-or-how-i-lost-my-sanity/

======
adrienthebo
Well, I didn't expect to see my own blog hit hacker news. This is exciting!
(Read: a bit terrifying.)

I wrote this blog post about a year and a half ago when Puppet 2.7.17 was
freshly released, and I was doing operations at Puppet Labs and was trying to
do some gnarly stuff with Puppet internals. I have a pretty bad memory, and
blogging about things I read was the only way to keep everything in my head.

Since I wrote this post, a number of things have changed. For one we've
prioritized clear documentation and we work hard to make sure that the code
itself is clear and understandable. Since I've been the one whining about poor
inline documentation, I've taken a swing at improving things myself
([https://github.com/puppetlabs/puppet/commit/447d24403f461743...](https://github.com/puppetlabs/puppet/commit/447d24403f461743c02ab58a11aed57a9b110082)),
because if I'm going to whine I better put up and make a change myself. In
addition Nan Liu/Dan Bode released the Types and Providers book
([http://goo.gl/DEJoAd](http://goo.gl/DEJoAd)) which does a great job of
explaining that layer of Puppet; if you're interested in extending that layer
of Puppet I would highly recommend it.

If anyone has questions I would be very happy to answer, and always if anyone
is interested on developing on Puppet I and the rest of the platform team
would be very happy to help out. We have #puppet-dev on irc.freenode.net; you
can ping me directly (nick is finch) and the rest of the devs are also very
helpful!

~~~
nkurz
Welcome back Adrien! Which is to say, if this comment appears beneath yours,
this is evidence you are no longer unfairly hellbanned. Unless of course the
administrators (in a pique of particular deviance) have taken to posting fake
reassuring responses to banned comments to further your sense of complacency.

------
CraigJPerry
Use an IDE.

I don't mean to trivialise a very real and hard problem, but the world being
what it is, cut yourself a break here and let an IDE do the heavy lifting of
allowing you to navigate and help understand a code base.

You'll NEVER be able to guarantee all APIs you'll ever work with are
adequately documented. That path leads to madness!

~~~
asdasf
What IDE would you recommend for a ruby code base?

~~~
CraigJPerry
Jetbrains Ruby mine. E.g.

    
    
        > Guys, I don’t have the FAINTEST FUCKING
        > IDEA why that string is being returned.
        > I don’t even know if the return value
        > for destroy is used at all, in which
        > case the last line is meaningless.
    

One way could be find usages: [http://www.jetbrains.com/ruby/webhelp/finding-
usages-in-proj...](http://www.jetbrains.com/ruby/webhelp/finding-usages-in-
project.html)

------
WestCoastJustin
For anyone looking to learn about Puppet (via a Vagrant virtual machine), I
have created a screencast about it @
[http://sysadmincasts.com/episodes/8-learning-puppet-with-
vag...](http://sysadmincasts.com/episodes/8-learning-puppet-with-vagrant)

------
pm90
_> As I’m going through all of this code, I’m hoping to start documenting the
classes I go through here and explain what’s going on._

YES.

One of my biggest productivity boosters when dealing with understanding code
written by others was to use Evernote to document all my ideas, theories of
how the code worked, tests to see if it really did work that way and final
result. By documenting everything, I can at least rule out theories that don't
work; I think this is at least part of what is known as the scientific method.

I hope this becomes a trend and many more people start documenting their
findings. Let google loose on all that data and you save thousands of man-
hours spent understanding code

~~~
toomuchtodo
Comments in code is a start. URLs to documentation in comments is better.

~~~
philsnow
depends. when the code changes, how do you enforce that the documentation
changes, and that they change in sync? depending on how you're storing the
documentation off to the side, do you have two versioning schemes to reconcile
when trying to look at code history? does you documentation even ha e
versioning?

if you keep the docs in the repo, during code review you can say "hey, update
the doc while you're at it" or "this doc change doesn't agree with this code
change, can you take another look at it?"

------
pc86
adrienthebo's account is < 30 minutes old and already hellbanned.

~~~
owenmarshall
Ridiculous. Absolutely ridiculous. And clearly evidence of a poorly designed
automated process running amok, because his comment is very informative.

------
bicknergseng
Mostly unrelated but kinda funny, this title looks like it was generated by
that random HN title generator posted a little bit ago.

~~~
talles
While an unfortunate coincidence I got to admit, it does look like it.

------
bachback
puppet isn't how things are supposed to be. for starters the initial learning
curve is steep. salt is more powerful and easier to get started.

------
almost
Hi adrienthebo, your comment is dead for some reason. I guess your new account
might have trigger a spam false positive and got hell banned (so it may appear
to be non-dead to you when you're logged in).

