Forum OpenACS Development: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS

1: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS

Posted by Peter Marklund on 01/13/03 12:15 PM

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

2: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by xx xx on 01/13/03 03:16 PM

Hi Peter, I agree. It is hard to keep track of 'where is what', since there seems no single place to store user's projects, documentation etcetera.

The FAQs about FAQs might describe a dynamic answer in some adjusted form. However, Faq is buried in the site under 3.2.5 documentation.
Or should we use https://openacs.org/bookmarks/
Or use https://openacs.org/projects/openacs/developers/side-projects

'The Place' could be a resource for official documentation. What do you think?

3: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by Roberto Mello on 01/13/03 04:15 PM

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

-Roberto

4: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by xx xx on 01/13/03 04:51 PM

That's true also. Definitely.

But isn't writing documentation like fighting doping in sports? We will always be one step or ten steps late.

5: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by Kjell Wooding on 01/13/03 07:14 PM

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.

6: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by xx xx on 01/13/03 11:12 PM

That is definitely a silly argument, Kjell, so why bring it up?

Good documentation is crucial, everybody knows. But I think nobody can document against the coding force in this community. New code is 'literally flowing in to HEAD' as Ola puts it.

I think the question was where to COLLECT ... If it wasn't for CVS, code itself would be scattered.

Just decide where and how to drop documentation and 'Best Practices / Conventions / Hidden Features / Howto' that one discovers or wants to share.

If not, too bad... we'll search the forum over and over again or we'll ask Tilmann 😊. The community helps out most of the times (thanks!).

9: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 6)

Posted by Simon at TCB on 01/14/03 11:29 AM

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.

7: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by Jun Yamog on 01/14/03 05:08 AM

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?

8: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by Jon Griffin on 01/14/03 05:13 AM

delete is a reserved word in sql. So for sql files we should make it del (it generally already is). Also for sql updates, I use set.

For tcl it is not as important.

10: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by Simon Carstensen on 01/14/03 11:47 AM

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.

That is certainly a valid point, but considering the complexity of OpenASC 4.6 I think telling newbies to go read the source code would be a bit extreme. I think documentation explaining the basic steps of installation and simple package development is required. Joel Aufrecht's new docs are great in that respect.

Apart from that I agree with you completely. Readable code is a better solution than outdated docs. Also good tools like the API documentation are essential - means of taking source code and turning it into documentation. OpenACS is too complex to simply read the source code and I'm not even sure that all functionality is represented in the packages (I was looking for ad_form syntax for checkboxes the other day without luck).

11: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by Andrew Piskorski on 01/14/03 08:54 PM

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.]

12: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 11)

Posted by Simon at TCB on 01/15/03 09:43 AM

Andrew,

Despite you feverent language, its not actually utter nonsense. In actual fact it forms part of the basis of a well know (and widely implemented) development methodology.

And, if I could just refer you to my earlier post in its entirety I think I did point out this applies only to techncal docs, not user guides/overviews etc.. i.e. one may as well, in projects like this, avoid the lenghy design docs that server little purpose after the code is released.

But thanks for misrepresenting what I said :o) How good it is to be be back ...

13: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 12)

Posted by Tilmann Singer on 01/15/03 10:19 AM

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.

14: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 13)

Posted by Simon at TCB on 01/15/03 11:08 AM

We do agree. I'm referring to technical desing documents. whihc at best shuld be minimal if at all. A design document is useful *prior* to implementation, but not afterward.

At least in this kind of project. I'm sure building software for missle guidance systems or airline operation requies a different approach, but thats hardly relevant here ;o)

Besides, reading code is actually quicker (and weill certainly be a true system description).

Ok, I'll accept that in an ideal world, with infinite resources that can work at the speed of light, then having perfectly matched documents is good.

But as thats not the case, whats the point of aimn at the unattainable, better to work with human nature and circumstance?

15: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 1)

Posted by Peter Marklund on 01/15/03 06:06 PM

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.

16: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 15)

Posted by Roberto Mello on 01/16/03 11:49 PM

I agree with Andrew and Peter.

Our current package developer documentation lacks much of the "why" that Andrew refers to. I've often found myself wandering through package code wondering why it was done that way.

I could see what it was doing, for the most part, but not having a document explaining "the big picture", and the reasons for that design, made the entire effort much more time consuming than it should be.

Instead of reading a blurb of the design of the package, which would help me get to what I wanted to change faster (or find out if I should be even interested in changing it), I had to look through file after file, proc after proc, like a compiler would, to understand it.

Clearly inneficient.

-Roberto