CodingStyleForOurPerlChanges
Development - parent
- This specifically applies to perl code, not Css, templates, or other non code areas.
- This is meant to deal with the immediate situation, eventually can back off on this as docs improve.
- paulej72 approval Sat Mar 8 2014
I am about to make a change that will affect maybe two dozen perl pages. I think it might be a good idea to consider the manner in which we do this now.
The initial days of this project were 'Pure Terror', and it is understandable that changes were made quickly and without much in the way of comment or attribution. However, the threat level is now down a bit closer to 'Solid Panic'. So I think it wise to at least begin to consider this.
The existing code style is, well, lets just call it 'inconsistent' and the commenting style might charitably be described as 'spartan'.
We have a mass of code which no one here had anything to do with the writing of, and which we do not yet fully understand.
Given this, I suggest our commenting style should be a bit closer to 'voluminous' than 'spartan'. This will allow us to actually help each other as we try to make sense of this code.
Here is a simple code change I am about to make to many pages, with its comments, and I believe it may have some useful characteristics we might follow in the future:
##########
#
# Code added Fri Mar 7 23:22:47 PST 2014 - Mike Demmers
# to add a private slash option.
# If database table 'vars' variable 'private_site' != 0 then site is private
# and all non-logged in users will be redirected to a login page.
# This code requires my $constants = getCurrentStatic(); declared earlier to
# insure the constant 'private_site' (set in admin interface, variables)
# is available locally. ( also $user = getCurrentUser(); )
# This routine must be added to all publicly available .pl scripts
# (pages, not inclusions), just prior to the first header() call.
#
if( $user->{is_anon} && $constants->{private_site} ) { redirect("/loginonly.shtml"); }
#
##########
Notes about what is there:
The comment is bracketed by very visible hashes.
########## # # ##########
Which clearly sets off our code changes off from previous ones. The hashes are hard left. This makes it easy to do a grep '^#' to find them, and if all our comments follow this pattern, easy to remove using automatic means like grep -v '^#'.
The code itself is indented to match the proper indentation level for the existing code, so the visual flow of the code is not broken.
# Code added Fri Mar 7 23:22:47 PST 2014 - Mike Demmers
The date of the change is clearly indicated, and who to blame. The date is just from 'date' and includes the time. The time, seemingly useless, is actually useful if seen as a unique identifier. I my case, I will be dding the same code to a number of files, so I will keep this header time the same for all of them. This means I can do a grep '23:22:47' *.pl and easiliy get a list of every file this change was made to at any time in the future.
# to add a private slash option.
Indicate what the general purpose of the code is.
# If database table 'vars' variable 'private_site' != 0 then site is private # and all non-logged in users will be redirected to a login page.
and exactly what it does to accomplish that.
# This code requires my $constants = getCurrentStatic(); declared earlier to # insure the constant 'private_site' (set in admin interface, variables) # is available locally. ( also $user = getCurrentUser(); )
Indicate any requirements to make this code work. In this case, it MUST be added to certain pages or the whole scheme will fail, so this gives someone makimng a new page an idea of what must be done.
# This routine must be added to all publicly available .pl scripts # (pages, not inclusions), just prior to the first header() call.
If there important interactions with other code, let the reader know. Don't make the next coder have to go backtracing through routine after routine just to see where a variable came from, etc. Just tell them.
Possible objections to 'voluminous commenting':
'This is interpreted code and large comments slow down processing.'
Answer:
1. We spend most of out time on development systems. We have been very quickly adding code tothe actual site, because of the situation. Eventually that will change and things willbe rolled out in a less panicky manner. This commenting style makes it EASY to remove the comments for the profuction version, if that is needed.
2. The whole production site is actually behind a cache. What is cached is NOT the perl code, it is the -results- of its work, the actual pages. The perl code only has to keep up with the requests of the cache, not all the users. So being a bit slow is not likely to have a big impact. If it does, see #1.
These are just my suggestions. If you have better ideas, let me know. The specifics of how the things mentioned above are done is unimportant. What IS important is that they are done.
-audioguy