> Before I pose my question, I'll state that I've always been on the side that > says one shouldn't have to re-document the C language for future coders. > ... a fellow programmer requested that I use comments to document a > very basic use of a ternary operator because not all programmers would > necessarily be familiar with it. Now, his stance is kinda dumb, but on the other hand, if the use were a bit strange and not entirely obvious at a quick glance, then yes, it should be commented. If (of course) it is something like: (i ? "true" : "false") Then there is no reason to comment it. > My question is this: How do people on this list feel about the notion > of documenting style, calling conventions, or other _complex_ > techniques being used in Circle, as well as in patches, snippets, etc? We (the CircleMUD team) have actually talked about this before and putting in some sort of "this is how/why we are doing things this way" document/comment/whatever into the code/distribution. To this point, we haven't really agreed on what should be in there, so of course, since we all have other things to do outside of the CircleMUD environment (except maybe George... (= ), we haven't gotten around to putting anything of the like together. > I also admit to some ignorance as to the state of the "coding" > document... See the FAQ. It's still quite valid on that point. *grin* It would be something that could go in a "finished" version, but we are nowhere near that at all (and at the rate we're going it will likely stay that way). As such, we encourage all user submitted documentation and when we do get around to the 'coding.doc' file, we'll likely use some of what is submitted (in some form at least) to build the "finished" version. We'll see. Ae. -- +---------------------------------------------------------------+ | FAQ: http://qsilver.queensu.ca/~fletchra/Circle/list-faq.html | | Archives: http://post.queensu.ca/listserv/wwwarch/circle.html | +---------------------------------------------------------------+
This archive was generated by hypermail 2b30 : 12/05/01 PST