Forum OpenACS Development: Re: Tipping of coding practices ?

Collapse
13: Re: Tipping of coding practices ? (response to 1)
Posted by Andrew Piskorski on 12/01/03 05:35 AM
Tom, in that case fine, but your own special definition of "documentation" is different from any normal usage of the word I've heard before, which confused me. I guess what you were getting at is that Dirk's original bullet item, "document code", is confusing and far, far too vague. Sorry, I misunderstood.

Instead of "document code" I would draft a guideline saying something like:

"Write clear, well commented code. Your comments in the code should explain WHY the code does something, wherever the why is not immediately obvious. If HOW the code does its work is especially tricky or confusing, then you should explain the how in a comment as well."

Jeff, yes, I take your and Dirk's point, but since I'm not going to volunteer (not anytime soon anyway) to write the coding standards doc and refactor lots of code, I might as well post to the forums. :)

Collapse
15: Re: Tipping of coding practices ? (response to 13)
Posted by Tom Jackson on 12/01/03 08:38 AM

Andrew, I really fail to understand why you seem to think that code is _not_ documentation. Since that is the only conclusion I can draw to your objection of my usage. Most of the code I have written I use. Example code which uses code is very good documentation of how, when and where to use an api.

Sometimes I think I fell into a worm hole here. If you look back at my original statements, you will see that a continue talking about documentation that clearly isn't code, so I understand that code is not the only documentation, just one form. If you overlook writing good code, by following a consistent style, it really doesn't matter how much external documentation you write about what the code does. As soon as something goes wrong, no one is going to want to fix it. There are many OpenACS packages which are documented, but are such a mess they are next to impossible to fix.

On the other hand, writing a good document on what you intend to do, what features you think a piece of software should have, what data model you want to use and why, will really save your butt if you have to put a project aside for any length of time to work on something else. I'm finally starting to get to a point where the excitement of a new project gets put into brainstroming, and not into furious writing of code to get something out the door.

Collapse
16: Re: Tipping of coding practices ? (response to 15)
Posted by Malte Sussdorff on 12/01/03 09:14 AM
Though code *can* be documentation, OpenACS is a very good example for code *should not* be documentation. We have a lot of ancient code within the system, that does not adhere to any standards set forth. Within the community we defined some standards by just adopting them, though some people still forget to do so, which is okay. My original question was only driving in the direction of getting a document of coding practises out (sad to hear Andrew has not time to do it, as he has a lot of ideas on that topic). And once we have these practises, we can encourage / enforce all *new* code to follow these practises.

Dirks point of cleaning up the code base is a very good one. I assume we might be able to do so during one of the OACS festivals with a lot of "worker bees" helping out. After all this is a good way for fresh developers to take a look at the code *and* learn the coding principles set forth.

My fear is that the principles will never be written down, unless I start to write this document. My hope is that Jade and Joel could devide this task between themselves. My goal is to not let this idea die and get documented coding principles out. Someday.

Collapse
17: Re: Tipping of coding practices ? (response to 16)
Posted by Joel Aufrecht on 12/01/03 09:22 PM
Jade's Things to remember when developing on OpenACS seem like a good place to start for coding standards.
Collapse
18: Re: Tipping of coding practices ? (response to 17)
Posted by Jade Rubick on 12/01/03 09:36 PM
Just for clarification, I did not create that list. It was assembled by Jun or someone else. Many people contributed to it. I just have it linked in from rubick.com

I think there's a thread a way back that describes putting that together.