On Tue, Sep 7, 2010 at 11:10 PM, Mark Engelberg <mark.engelb...@gmail.com> wrote: > What pre-conditions need to be met by the inputs? > What invariants are maintained by the function? > What are the performance guarantees of the function?
And this can't be expressed in a single sentence? > Many times there are dozens of functions that are interrelated. Only > one or two of them are the crucially important "entry points" that > provide the high-level API. Then reorganize your files. Each file should have a specific public API. > Good documentation makes > it clear what is "the right way". Fix the code. The "right way" should be the only / obvious way. > The list goes on. I just don't see these questions arising from an agile point of view... > If you want to comment your code for other > people to maintain it, that's even more challenging. Nonsense. That's all about good, descriptive naming. If you can't document your code in a single sentence, it's too complex. I keep hearing FP folks talking about small functions and breaking things down so this issue of documentation runs counter to that... > "Always code as if the guy who ends up maintaining your code will be a > violent psychopath who knows where you live." -- John F. Woods Most people who read my code have said it reads like poetry and they love it. I have almost zero comments in my code. I have literate function / variable names. Comments can get out of sync with code so the fewer comments you have, the better, as far as I'm concerned. The code itself should be literate. -- Sean A Corfield -- (904) 302-SEAN Railo Technologies, Inc. -- http://getrailo.com/ An Architect's View -- http://corfield.org/ "If you're not annoying somebody, you're not really alive." -- Margaret Atwood -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
