5 ms·
Reading the Puppet Source - Or, How I Lost My Sanity
- pm90 13y ago>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 13y agoComments in code is a start. URLs to documentation in comments is better.
- philsnow 13y agodepends. 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?"
- WestCoastJustin 13y agoFor 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-vagrant http://sysadmincasts.com/episodes/8-learning-puppet-with-vag...
- CraigJPerry 13y agoUse 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 13y agoWhat IDE would you recommend for a ruby code base?
- deleted 13y ago[deleted]
- CraigJPerry 13y agoJetbrains 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-project.html http://www.jetbrains.com/ruby/webhelp/finding-usages-in-proj...
- edwinnathaniel 13y agoMost of Java OSS projects out there have excellent documentation (albeit some are only at the JavaDocs level but not overall/high-overview type). 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).
- fit2rule 13y agoI beg to differ. Cscope, vim, make .. gcc. These are all the things you need to navigate a great codebase with plenty of online documentation. 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.
- bicknergseng 13y agoMostly unrelated but kinda funny, this title looks like it was generated by that random HN title generator posted a little bit ago.
- talles 13y agoWhile an unfortunate coincidence I got to admit, it does look like it.
- adrienthebo 13y agoWell, 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/447d24403f461743c02ab58a11aed57a9b110082 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 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 13y agoWelcome 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.
- pc86 13y agoadrienthebo's account is < 30 minutes old and already hellbanned.
- owenmarshall 13y agoRidiculous. Absolutely ridiculous. And clearly evidence of a poorly designed automated process running amok, because his comment is very informative.
- almost 13y agoHi 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).
- bachback 13y agopuppet 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.