Hello everyone, It has been suggested a number of times before that we come up with a standard style for Koha scripts in order to make the scripts easier to read. One such way of doing this is using a program called perltidy to go through and format things in a certain style. Perltidy can read its configuration from a seperate file, which would allow us to maintain consistency within the codebase. Now, there are a number of options that we should decide on before we can effectively use perltidy. I will present some of the major options here along with their alternatives and some sample pieces of code formatted with the various options. 1. Line length: This setting will prevent lines of code from exceeding a maximum number of characters. The default length is 80 columns. Do we want it do be more or less or the same? 2. Indentation: There are a number of ways that perltidy handles indentation. First, you can specify a number of spaces to ident code blocks. Shown below is the indentation set to 4 spaces: if ( $flag eq "a" ) { $anchor = $header; } We can change this value to anything we would like. We can also set it to use tabs instead of spaces to indent. 3. Opening Brace Right or Left: This setting controls where the opening brace for code blocks go. Below is an exmaple with them on the right: if ( $flag eq "h" ) { $headers = 0; } and on the left: if ( $flag eq "h" ) { $headers = 0; } Which one of these should we use? 4: Cuddled Else: The cuddled else style is shown below: if ( $flag eq "h" ) { $headers = 0; } elsif ( $flag eq "f" ) { $sectiontype = 3; } else { print "invalid option: " . substr( $arg, $i, 1 ) . "\n"; dohelp(); } while the non-cuddled else is: if ( $flag eq "h" ) { $headers = 0; } elsif ( $flag eq "f" ) { $sectiontype = 3; } else { print "invalid option: " . substr( $arg, $i, 1 ) . "\n"; dohelp(); } Which one is preferable. 5. Horizontal Tightness: This controls the spacing for items in "containers." Here are the various options: if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default) if ((my $len_tab = length($tabstr)) > 0) { # -pt=2 Note that that was for parentheses. There are similar options for square brackets, curcly braces, and code block curly braces. Those are a few of the major ones; however, there are more options at http://perltidy.sourceforge.net/stylekey.html. If you can think of anything else that would be beneficial style-wise, let me know. If you would please give me your comments and opinions (preferably along with why you think that way would be best for Koha), I would greatly appreciate it. Hopefully we will be able to get a standard style for Koha from this thread. Thanks, Mike -- Mike Hansen <mwhansen@hmc.edu>
Mike Hansen <mwhansen@hmc.edu> wrote:
1. Line length: This setting will prevent lines of code from exceeding
I suspect it's better to leave this to the discretion of the writers.
2. Indentation: There are a number of ways that perltidy handles
Single tabs, as then it's easy to change the number of spaces represented in a viewer/editor.
3. Opening Brace Right or Left: This setting controls where the
Can't remember which I prefer. I think left makes some things easier, but more people write right.
4: Cuddled Else: The cuddled else style is shown below:
Non.
5. Horizontal Tightness: This controls the spacing for items in
As tight as you can. My Opinion Only. -- MJR http://mjr.towers.org.uk/ IM: slef@jabber.at This is my home web site. This for Jabber Messaging. How's my writing? Let me know via any of my contact details.
Mike Hansen wrote:
Hello everyone,
Now, there are a number of options that we should decide on before we can effectively use perltidy. I will present some of the major options here along with their alternatives and some sample pieces of code formatted with the various options.
Good. My 2cts : As i've coded 95% of the MARC stuff and a lot of other scripts too, my opinion and how i use to do will probably decide what we do. Note I don't want to begin a war, but there is no "best" solution, otherwise everybody would use it.
1. Line length: This setting will prevent lines of code from exceeding a maximum number of characters. The default length is 80 columns. Do we want it do be more or less or the same?
I don't worry with this.
2. Indentation: There are a number of ways that perltidy handles indentation. First, you can specify a number of spaces to ident code blocks. Shown below is the indentation set to 4 spaces: if ( $flag eq "a" ) { $anchor = $header; } We can change this value to anything we would like. We can also set it to use tabs instead of spaces to indent.
I prefer using tabs => ppl can decide the size of the tab in their editor. It's only a problem with tabbed comment at end of line, but that's not a major pb, as there are only a few of such comments. We can decide to prefer a "4 char tab" anyway. Not I've "tabbed" a lot of scripts I haven't written (on the fly)
3. Opening Brace Right or Left: This setting controls where the opening brace for code blocks go. Below is an exmaple with them on the right: if ( $flag eq "h" ) { $headers = 0; } Which one of these should we use?
I always use right one.
4: Cuddled Else: The cuddled else style is shown below: if ( $flag eq "h" ) { $headers = 0; } elsif ( $flag eq "f" ) { $sectiontype = 3; } else { print "invalid option: " . substr( $arg, $i, 1 ) . "\n"; dohelp(); } Which one is preferable.
I usually use cuddled else.
5. Horizontal Tightness: This controls the spacing for items in "containers." Here are the various options: if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default) if ((my $len_tab = length($tabstr)) > 0) { # -pt=2 Note that that was for parentheses. There are similar options for square brackets, curcly braces, and code block curly braces.
No rules for me. Probably pt=2 most of the time. Not that when the condition is complex, I sometimes use multi-line writting.
Those are a few of the major ones; however, there are more options at http://perltidy.sourceforge.net/stylekey.html. If you can think of anything else that would be beneficial style-wise, let me know. If you would please give me your comments and opinions (preferably along with why you think that way would be best for Koha), I would greatly appreciate it. Hopefully we will be able to get a standard style for Koha from this thread.
Usually, I prefer less line-eating form of coding. For example : Opening Vertical Tightness $dbh = DBI->connect( undef, undef, undef, { PrintError => 0, RaiseError => 1 } ); and NOT : $dbh = DBI->connect( undef, undef, undef, { PrintError => 0, RaiseError => 1 } ); -- Paul POULAIN Consultant indépendant en logiciels libres responsable francophone de koha (SIGB libre http://www.koha-fr.org)
One more idea : in templates, how to write HTML ? I suggest : ======= 1- when something is open/closed in a short area, it's in the same line : <td> </td> Otherwise, it's indented on some lines : <form action='<TMPL_VAR name=action>' name=Aform method=post> <input type=hidden name=op value='add_validate'> <table> <tr> <td>Code annexe</td> <td> <TMPL_IF name="branchcode"> <input type=hidden name=branchcode> <TMPL_VAR name="branchcode"> <TMPL_ELSE> <input type=text name=branchcode size=5 maxlength=5> </TMPL_IF> </td> </tr> </table> </form> 2- As suggested in html::template doc, HTML::template tags are uppercase <TMPL_VAR name="smthg"> 3- as required in w3c html : everything in right part of a token has "" (<input type="text" value="help"> : text and help is on the right) (it's mandatory when a non-alpha char is present, it's a good idea to always use it). -- Paul POULAIN Consultant indépendant en logiciels libres responsable francophone de koha (SIGB libre http://www.koha-fr.org)
participants (3)
-
Mike Hansen -
MJ Ray -
paul POULAIN