Thanks for that explanation - I hadn't fully looked at codeq and how it works - I can see that it might make management of external documentation an easier task; especially for a codebase that changes slowly.
- Korny On 22 January 2013 18:39, Rich Morin <r...@cfcl.com> wrote: > 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 > -- Kornelis Sietsma korny at my surname dot com http://korny.info "We do not quit playing because we grow old, we grow old because we quit playing" - O.W. Holmes -- -- 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
