On Wed, Sep 8, 2010 at 1:18 AM, Mark Engelberg <mark.engelb...@gmail.com> wrote: > I don't know that I'd be flattered by that comparison :)
LOL. Point well taken :) > If you ever read an article presenting some new algorithm, data > structure, etc. in an academic journal, the published article will > certainly contain some actual prose describing what's going on. Well, yes, certainly, but that's very different from what I'd normally expect as documentation for code itself. > considerably in terms of scope and complexity. The Flash API > documentation is very well written and it fills two 600+-page volumes. And that's necessary because it's a very complex library that you need to know a lot about it in order to use it (at all). It's complex enough that there are a myriad books about it and week-long courses and so on. But the official Adobe documentation is developed and maintained by a whole team of full-time writers - and it's developed separate from the code itself (which is why sometimes the documentation has errors and omissions in it). [Disclaimer: I worked at Macromedia for six years and then Adobe for a year and for a while was working with the AS3 spec folks and developing the compiler test suite] > Our preferences are shaped by our experiences, of course, and your > mileage may vary. What is the largest body of code you've tried to > read and understand and maintain? Were you able to talk with > developers about the code, or did you just have to understand it by > reading it? What things did you like and dislike about the > readability of their code? The largest in-place code base I've come into as 'the new guy' was about 100k lines. The lead developer left essentially within a few days of me joining so although I had access to two other developers, I mostly had to come to speed by myself by reading the code. Luckily, it was a company with strong coding guidelines and the software itself was source code analysis tools which were used extensively on its own source code to automate compliance. The source code was not heavily commented (that was part of their coding guidelines - on the grounds that code should be simple and clear enough not to need many comments) but good naming conventions and good structure many it easy to navigate and assimilate. That system grew to about 250k lines while I was working with that team and we kept tightening the automated code checking. That was the early 90's and the company is still going and has added new product lines... Most of the other sizable projects I've worked on, I've come in near 'ground zero' and have ended up anywhere between 20k and 200k lines. > My experience aligns well with the points raised in this essay I'm in two minds about Joel. He's a great speaker and a great story teller and a lot of his posts are engaging and have interesting and/or useful observations in. But he plays very heavily on "Fog Creek only hires the best" and the whole thing about rock star developers and that undermines some of the other stuff he says (at least for me). I think that all code can be improved. I really enjoy the opportunity to improve my own code when I have to revisit it. I try to encourage others to improve my code too. But I think the reason a lot of developers want to rewrite other people's code is twofold: * many developers are too lazy to spend the effort to understand other people's code (or learn good practices) * a lot of code really is crap (because we have lots of poor developers in our industry... who are too lazy to learn good practices) > I think just about our only point of agreement is that I also feel > that it is difficult to maintain documentation that is separate from > the code. Yup, definitely agree. Being able to attach doc-strings to function arguments helps a lot, in my experience. I haven't yet seen a really good way to attach extended documentation to code - it's definitely a hard problem to solve. I'm with you on liking tools to automate things tho'... -- 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
