Today Lars taught me about how to execute code upon package instantiation and proposed new naming conventions for Tcl procedures that create, update, and delete objects.

This all reminded me that we need a document where we can collect conventions, best practices, and features. Tilmann pointed me to Yun's Things to remember document:

http://www.infiniteinfo.com/openacs/things2remember.html

which certainly looks like a good start.

Of course such a document would have to fit in to the current developers guide (which should be updated to be for 4.6 now, right?). I haven't read the documentation in a while so I don't know exactly what the best structure is.

/Peter

IMHO I think we should just fix/re-write the Developer documentation, and include the best practices in it.

-Roberto

That's a silly argument. "Don't document, because it will never be up to date."

Yes, the developer documentation should be updated with best practices. Remember: the code itself is intended to be self-documenting (through the magic of ad-proc). Meta-information like best practices needs to be done out of band.

Documentation is a cultural issue. Once developers get into the mindset of "Fix the documentation when you fix the code," the documentation task is no longer onerous.

Hi Peter,

I am still looking at the naming conventions, atleast for the cms that I am working on, here are my conventions.

get_[item/folder/etc.]
list_[item/folder/etc.]
treelist_[item/folder/etc.]
delete_[item/folder/etc.]
create_[item/folder/etc.]
edit_[item/folder/etc.]

Also some other convention, for example "get_item_by_url", where in "get_item" is the basic above followed by something more descriptive "by_url".

Although its not easy to do as you go along.  It takes me review and refactor the code again.

Roberto,

Is there some way put things2remember in openacs.org?

Its not actually such a silly argument. These days theres a growing acceptance that the cost/effort curve for technical documentation is often prohibitive. In fact, (and I refer to technical docs only) the code should be the best document available, as, after all, it is the only thing 'guaranteed' to be accurate.

One might argue (as XP does) that if you can't read/understand source code, you have no business working with it at a technical level.

Also, you could argue that documentation actually makes things worse in the long run, particularly when you *know* you don't have the resources. What you end up with is inaccurate docs that confuse instead of help.

In an open, voluntary community such as this then focusing on more 'readable', simpler code may be a better use of labour. Leave doc'ing to a commercial effort.

I should point out I'm not necessarily a proponent of all this, but I'm prepared to beleive that perhaps the whole traditional approach to documentation is flawed.

This is kind of off topic, but this comment really rubbed me the wrong way:

One might argue (as XP does) that if you can't read/understand source code, you have no business working with it at a technical level.

Utter nonsense - a meaningless straw man argument. I can always read and understand what code does. (Eventually anyway, at worst. Algorithms so intricate and tricky that understanding the implementation is truly beyond all but a select few are probably extrememely rare.)

What I cannot ever get from just reading the code, is why the code does that - why the programmer chose to do it that way. What was his thinking, and what design/implementation goals led him to write that code? Is that weird looking bit because the programmer just wasn't very good, or is it a critical but subtle bug fix that a master programmer put it in, but never bothered to comment as such?

That sort of "why" information is what needs to go into good code comments. IMNSHO that's the by far the single most important thing to go into comments. Probably that applies to developer docs too. Certainly, developer docs should have all the big picture orientation stuff - what are all the moving parts, what parts do what, why do they do that, what bodies of code are relevent to each part, that sort of thing.

[End rant.]

I cannot imagine that this well known methodology advocates leaving a developer who needs to work with existing software written by someone else totally clueless about the purpose of that software. I think the typical 'Big Picture' paragraph at least is essential for every OpenACS package - why should other developers waste hours finding out what the original author could provide in a few minutes? But propably we agree on this anyway, it's just not really clear to me from the previous comments.

I think I can understand both sides in this discussion. I do subscribe to the XP philosophy and how they stress avoiding duplication of information, i.e. don't say something in the documentation that can be read from the code.

On the other hand I still feel, and I think most people agree, that there still is a strong case for technical documentation. At many times it may not be possible to learn easily from the code base what constitutes best programming practice. Different applications may take different approaches, which one should the novice developer choose? Also, as Andrew so well points out, the code doesn't necessarily communicate the design tradeoffs, known limitations or the concepts and use-cases that drove development.

We should try to keep code level information in our docs that can be expected to change to a minimum and rather link to a dynamic api documentation. We must also try to keep whatever duplication still ends up in the docs in sync with the code.

As a reader of technical documentation you are typically aware of the fact that every implementation detail may not be 100% accurate. However, that doesn't render the documentation useless. I believe the design documents that we have inherited from aD illustrate this point.