Dave Fayram wrote: > > If you want to explain why you did something, that's what a whitepaper > or tech memo is for. Your code isn't the place to justify your position > post facto. The fact that the code works should be justification > enough. :) Yeah; I've written lots of code that, um worked. It just worked at the wrong thing. > > Inevitably, the documentation-heavy approach (comment-driven > development) leads to a design-up-front methodology. And I think we > have a mountain of evidence that the Waterfall Method and similar > up-front design methodologies are impractical at best. I don't see how one goes from writing comments to having a documentation-heavy approach. Or how it equates to up-front design. > > I'm a big fan of documentation and code that lends itself to the > reader, and Ruby helps me with this, but my feeling is that if your > methods are so long that they require comments, then your methods are > too long. Sure, there are exceptions to this (explaining a tricky step, > saying why a non-obvious piece of code exists, naming a pattern or > algorithm), but in general I think this is a reaction to bad coding > practice. But a better approach might be to write the method comment first, then convert the comment to code, such that the comment is no longer needed. And if you find that you cannot do this, then that may be a code smell. Or, the comments that remain are higher-level observations that have no code equivalent, and should stay. I believe that developers can forget that what seems obvious at the time the code is written will often seem cryptic later on, ever to the one who wrote it. Writing it down forces you to at least make the point explicit, and help the coder see if he or she has a clear understanding of what code is supposed to do. I find the a best way to know if I understand something is to try to write about it. It forces me think in a certain way that talking or coding does not. Writing is a unit test for the brain. > > I really like the Ruby communitiy's approach to documentation. Document > *what* functions do, give examples of class usage, provide rich unit > tests. But seldom do I see a project give step-by-step comments, > explain what variables are (beyond their name), or explain motiviations > in the code. This means we have beautiful Rdoc outputs and clean code. That's great when it happens. But there is too much core ruby rdoc that simply gives an obtuse method and a set of terse variable names. Not a word on what the method does. > > Strictly speaking, the Rails documentation would fail this guy's > criterion for good documentation. But I think pretty much anyone who's > used Rails (and gotten past the awkward, "Where do I start" step) can > testify that the Rails documentation is complete and well-done. Not everyone agrees with that. I'm past the "Where do I start" step and routinely have problems understanding how to do what should be simple tasks. James -- http://www.ruby-doc.org http://www.rubyxml.com http://catapult.rubyforge.com http://orbjson.rubyforge.com http://ooo4r.rubyforge.com http://www.jamesbritt.com