On Jan 21, 2013, at 23:15, Korny Sietsma wrote: > The flip side, of course, is that having documentation separate from > code often leads to the documentation becoming out of sync with thecode. > > What happens when someone renames or moves some code, but doesn't also > move the docs? What happens if they change the implementation? Will > people remember that every code change might potentially also require a > change to documentation, stored somewhere else, and potentially versioned > independently?
[ Andy addressed this question, but I have my own spin on it, so... ] Keeping the docs with the code helps to handle this problem, because it makes it easier for a programmer to spot inconsistencies between the docs and the adjacent code. However, we can't force the programmer to look at the docs, let alone keep them up to date. In any case, putting the docs in with the code causes the other problems we've discussed (eg, bulking up the code base, making changes difficult, getting in the way of helpful markup, internationalization issues). So the real question is whether Codeq offers a way to keep the docs current. I believe that it does, in a very natural fashion. Codeq tracks "code quanta" (ie, meaningful subsets of files such as classes, methods, and functions). If Rich Hickey changes either the code or the comments in the foo function, Codeq will soon know about the changes. It can then send an alert to anyone who is interested in making sure the external documentation for the function stays current. Given that Rich won't change any given function very often, this isn't likely to result in a large number of alerts, updates, etc. I agree that this isn't a perfect solution, but I think it is probably quite workable. -r -- http://www.cfcl.com/rdm Rich Morin http://www.cfcl.com/rdm/resume r...@cfcl.com http://www.cfcl.com/rdm/weblog +1 650-873-7841 Software system design, development, and documentation -- 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
