On Tue, Sep 7, 2010 at 10:23 PM, Sean Corfield <seancorfi...@gmail.com> wrote: > I'm watching this thread and I'm wondering what kind of documentation > people are talking about here. I've always been used to using > self-documenting function / variable names and short comments for > documenting everything. Clearly you guys are talking about something > much bigger than this and I'd like a bit more insight into that. Who > are you writing this documentation for? How detailed does it need to > be? Why are good function and variable names and a short summary not > enough?
A few things off the top of my head: Functions: 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? Examples of how to use the function and why you'd want to use the function. What other functions are needed to create the structures consumed by this function, and what functions use the structures it outputs? In other words, is this function truly indpendent, or is it typically used as part of a chain of function calls? What external dependencies does it have? (e.g., if it depends on another library, tool, file format, database etc, and that library changes, you'd better take another look at this function to make sure it still works and delivers the same guarantees it did before). Files: 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. The rest are mostly helper functions that implement the lower-level details. They are made public because in some situations, you might want to have access to those lower-level details, but 99% of the time, you can ignore them. By default, all of these functions will show up in an auto-generated API listing. Good documentation will direct you to the important functions. What is the organization scheme that determines how the functions are split across files? In other words, how do you go about finding the namespace that implements the functionality you're looking for. Often, large projects accumulate a certain amount of functions that were produced as some sort of dead-end or deprecated approach. The functions are kept around to support consumers who use them, but they are no longer the "right way" to do things. Good documentation makes it clear what is "the right way". The list goes on. And these are only the things that are important to consumers of your code. If you want to comment your code for other people to maintain it, that's even more challenging. You have to make a convincing case that the function actually works the way you intend it, and other people will need to understand it enough to change it without breaking it (and to be sure the change won't break something else that depends on it). Who do I write for? Usually I write for myself two years down the road. That's enough of an incentive to make me want to keep my code well-organized, although I don't have to go a great deal into my implementation decisions and details because I can probably reconstruct that if I need to. Also, I'm pretty familiar with my own style for naming variables, so there's no need to go into that. When I write code for other people to read, I find I have to be even more rigorous in my documentation since the things that are obvious to me will be not so obvious to them. One person's concept of "self-documenting names" doesn't necessarily correspond to another's. A great quote: "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 -- 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
