Re: [SM-DEVEL] Coding Practises

[Jonathan A. <jo...@sq...>]

Hello Marc,
On Wednesday, May 21, 2003, Marc Groot Koerkamp wrote...

>> ESPECIALLY when there are multiple if/case/while/for statements.
>> That also applies for classes as well. It certainly makes reading a
>> hell of a lot easier. Take writeBody function in the deliver class.

> <snip>

> Yes Deliver.class.php is messed up by me. Originally everything was
> nicely tabbed but somehow an editor messed up everything and I
> didn't noticed it (Midnight Commander from shell)

That is something Erin brought up. Some editors let you define how
many spaces should be used to represent a tab. For example if I set
mine to use 4 spaces to display a tab, and you set yours to 8, but we
all agree to use spaces instead of tabs in the future, I'm going to
see that the old code has what appears to be four spaces while it
really is a tab.

> I commit the Deliver.class.php in a minute and I removed all the
> tabs by 4 spaces :-)

Yay... thanks ;)

> A few add ons regarding coding practice:

> My personal preferences regarding switch statements:

>     switch ($var)
>     {
>     case:
>         [code]
>     default: break;
>     }

I'd put the opening { on the line with switch. I'm not sure about the
case: being inline with switch though.

> About comments:

>   I think it would be a good thing to document all function arguments
>   and the returned values.

Absolutely, and maybe a basic description of the function.

>   A short explanations of the required type (str, bool, int, array) and
>   what it does. Optional an Author name isn't a bad thing either.

>   Currently I'm documenting some of my work in progress code like that but
>   before I finish that I think it would be a good thing to agree on the
>   minimal requirements and the format.

I don't think there is much in the way of a "minimal requirements" for
comments... I'd just like to see more... They might also be useful to
append when fixing bugs as well, and why you'd made changes if it was
major, where as if it is something like adding a var like was the case
with the delivery class, then I don't think it's really needed. But
use your own imagination as to what really needs to be put in. A good
example I guess is in functions/global.php the sqgetGlobalVar, tells
you what it is, what it does, an example, and the possible return
values and what they mean. Erin even noted in the code she had to fix
that constants shouldn't be enclosed in '' when trying to use a case
statement.

-- 
Jonathan Angliss
(jo...@sq...)