Reading the Puppet Source - Or, How I Lost My Sanity
somethingsinistral.net
somethingsinistral.net
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...), 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) 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!
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!
> 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.
I'm very thankful for the community that pushes this type of mentality (good documentation).
Having said that, yes, IDE. Specifically: modern IDE.
I noticed that Sublime is somewhat sits in-between a Text-Editor and an IDE. I've never used Sublime that heavy yet so I can't vouch for it.
But I can definitely vouch for IntellIJ (and its family: RubyMine, PyCharm, WebStorm).
The 100% source-onboard setup, wherein you do actually have sources to every single thing, means .. if you're sane .. documentation problems don't get in your way of reading the code.
They work with large C++ codebase and Linux C kernel.
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
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?"