Legal Notices
A disclaimer notice of the code legal status is important to determine the availability and originality of the code.
The recommended disclaimer notice does not allow edits to be made, nor reuse of the code.
Standard Disclaimer
# /*--------------------------------------------------------------*/ # /* DISCLAIMER NOTICE */ # /* */ # /* This document and/or portions of the material and data */ # /* furnished herewith, was developed under sponsorship of the */ # /* U.S. Government. Neither the U.S. nor the U.S.D.O.E., nor */ # /* the Leland Stanford Junior University, nor their employees, */ # /* nor their respective contractors, subcontractors, or their */ # /* employees, makes any warranty, express or implied, or */ # /* assumes any liability or responsibility for accuracy, */ # /* completeness or usefulness of any information, apparatus, */ # /* product or process disclosed, or represents that its use */ # /* will not infringe privately-owned rights. Mention of any */ # /* product, its manufacturer, or suppliers shall not, nor is it */ # /* intended to, imply approval, disapproval, or fitness for any */ # /* particular use. The U.S. and the University at all times */ # /* retain the right to use and disseminate same for any purpose */ # /* whatsoever. */ # /*--------------------------------------------------------------*/ # /* Copyright (c) 2006 */ # /* The Board of Trustees of */ # /* the Leland Stanford Junior University. All Rights Reserved. */
A second, more flexible disclaimer notice is also recommended that waives all copyright of the code. It is recommended for shared projects and collaborations.
Public Domain Disclaimer
# /*---------------------------------------------------------------*/ # /* STANFORD UNIVERSITY NOTICES FOR SLAC SOFTWARE */ # /* ON WHICH COPYRIGHT IS DISCLAIMED */ # /* */ # /* AUTHORSHIP */ # /* This software was created by <insert names>, Stanford Linear */ # /* Accelerator Center, Stanford University. */ # /* */ # /* ACKNOWLEDGEMENT OF SPONSORSHIP */ # /* This software was produced by the Stanford Linear Accelerator */ # /* Center, Stanford University, under Contract DE-AC03-76SFO0515 */ # /* with the Department of Energy. */ # /* */ # /* GOVERNMENT DISCLAIMER OF LIABILITY */ # /* Neither the United States nor the United States Department of */ # /* Energy, nor any of their employees, makes any warranty, */ # /* express or implied, or assumes any legal liability or */ # /* responsibility for the accuracy, completeness, or usefulness */ # /* of any data, apparatus, product, or process disclosed, or */ # /* represents that its use would not infringe privately owned */ # /* rights. */ # /* */ # /* STANFORD DISCLAIMER OF LIABILITY */ # /* Stanford University makes no representations or warranties, */ # /* express or implied, nor assumes any liability for the use of */ # /* this software. */ # /* */ # /* STANFORD DISCLAIMER OF COPYRIGHT */ # /* Stanford University, owner of the copyright, hereby disclaims */ # /* its copyright and all other rights in this software. Hence, */ # /* anyone may freely use it for any purpose without restriction. */ # /* */ # /* MAINTENANCE OF NOTICES */ # /* In the interest of clarity regarding the origin and status of */ # /* this SLAC software, this and all the preceding Stanford */ # /* University notices are to remain affixed to any copy or */ # /* derivative of this software made or distributed by the */ # /* recipient and are to be affixed to any copy of software made */ # /* or distributed by the recipient that contains a copy or */ # /* derivative of this software. */ # /* */ # /* SLAC Software Notices, Set 4 (OTT.002a, 2004 FEB 03) */ # /*---------------------------------------------------------------*/
Code Introduction
Provide a description of the script's or a subroutine's function, what input it uses and what output it produces. It is often helpful to include examples of input and output.- Provide the author and creation date.
- Provide information on how to use the script (some examples are usually useful), including any options and their default values.
Perl Syntax Checking
All perl modules should be checked for possible syntax errors using the {{perl -c}}option.Declare Imporant Variables Beforehand
It is a good practice that all the variables should be declared, using
$my or $our or $local. Make use of the strict feature to adhere to these issues.Tainting
Unable to render {include} The included page could not be found.
File Access
Unable to render {include} The included page could not be found.
Error Codes and Warnings
Check return codes of any functions called (e.g. opening or closing a file) and provide a diagnostic message for anomalous results together with the error code(s).For warnings, diagnostics, and information about how the script is working etc. use STDERR. For the output that is the purpose of the script use STDOUT so the output can be piped to another process.
Script Output
If the script produces a report, then include in the report output, the name of the script that created it (you can usually use
script (
$0), the time it was created (use scalar(logtime())), whom to contact for further information and/or who ran the script (
scalar(getpwuid($<))). It is also good to include the name of the host that ran the script. One way to do this is:
use Sys::Hostname;
#use Socket;
my $ipaddr=gethostbyname(hostname());
my ($a, $b, $c, $d)=unpack('C4',$ipaddr);
my ($hostname,$aliases, $addrtype, $length, @addrs)=gethostbyaddr($ipaddr,2);
Code Reuse
Where possible re-use code rather than replicating it, this should result in easier maintenance. Subroutines can help in this.See IEPM Perl Modules for further details.
Code Commenting
Kindly ensure that the code is properly commented. There should be comments, if not with each statement, then at least with each block of code or loop. For instance a file or a major block of code should begin with purpose and description of the code:
Perldoc?
Perhaps we should be stressing the use of perldoc also?
########################################## #Get TULIP responsive host distances between Guthrie and Tulip # The Input gives the IP addresses and distances of responsive TULIP hosts # Example: # 30.87.34.2,8551.236157 # 140.181.96.29,18488.23791 # 203.181.248.234,5148.805353 # 203.181.248.241,5148.805353 # 134.160.224.254,16684.70444 # 136.142.111.46,1685.3686 # Returns: # A hash associated with the IP addresses with the value distance,
Each subroutine should also have a brief description like:
###########################################
#Executes synack to a target, and parses the results to provide
# 0 if successful or -1 otherwise. If unsuccessful then prints
#an error message to STDOUT.
# The target is provided in the argument, i.e. $_[0]
#Example of Unix synack output that is parsed by this sub:
#SYN-ACK to dns1.ethz.ch (129.132.98.12), 4 Packets
#
# connection for seq no: 0 timed out within 1.000 Secs
# connection for seq no: 1 timed out within 1.000 Secs
# connection for seq no: 2 timed out within 1.000 Secs
# connection for seq no: 3 timed out within 1.000 Secs
#
# Waiting for outstanding packets (if any)..........
#
#
# ***** Round Trip Statistics of SYN-ACK to dns1.ethz.ch (Port = 22) ******
# 4 packets transmitted, 0 packets received, 100.00 percent packet loss
# round-trip (ms) min/avg/max = 0.000/0.000/0.000 (std = 0.000)
# (median = 0.000) (interquartile range = 0.000)
# (25 percentile = 0.000) (75 percentile = 0.000)
sub synack {
my $target=$_[0];
if($^O=~"linux") {
my $success=0;
...
It is always good to maintain a change history. It is of great help when applications are in production environments and someone needs to make a slight modification. So include a version number and date and the major changes made for this version, comment older version numbers and their descriptions, for example:
#my $version="3.73, 3/2/06, Les Cottrell"; # Replaced use of uname with $^O to improve tainting # Increased the debug output to show the pwd #my $version="3.74, 5/8/06, Les Cottrell"; #Enabled pings from onsite to onsite my $version="4.0, 5/13/06, Les Cottrell"; #Added synack for SLAC
CVS
We are in the process of shifting everything into CVS. Putting versioning into the code is ugly and not very useful.
The rule of the thumb is to keep this thing in mind while coding.
"How would it feel if someone provided me a similar code and I had to make one small
change and it took me a whole day just to point out that one line!! So if I don't want to mess up someone's day, I better put useful comments."
Layout Style
See IEPM Perl Coding Styles
Also, go through the following link for better understanding. http://perl.apache.org/docs/2.0/devel/core/coding_style.html
Variable and File Names
Variable and files names often convey more than comments. Try to use good variable names. Long names are not always good, but sometimes it is important for the message to be conveyed. http://www.unix.org.ua/orelly/linux/cgi/ch16_02.htm
Avoid using the same names repeatedly, for instance if downsites is a script, it should not be the name of the database. Just like you don't want to name your kids Waqar1, Waqar2 and Waqar3, you should not name the files downsites, downsites10 and downsites2.
Golden Principles:
To get a brief overview of the golden principles, please see:
http://www.bbc.co.uk/guidelines/newmedia/technical/perl.shtml http://www.wpi.edu/Pubs/Policies/Web/CGI/guidelines.html
Options
Use
Getopt (see Perl manual) for options. If you need options then you must also add a USAGE section to your code. An example of a USAGE is given below:
(my $progname = $0) =~ s'^.*/''; # strip path components, if any
my $allurl =
'http://www-iepm.slac.stanford.edu/cgi-wrap/pingtable.pl?format=tsv'
. '&file=minimum_rtt&by=by-node&size=100&tick=allmonthly&from=WORLD'
. '&to=WORLD&ex=none&dataset=hep&percentage=any';
my $dir = "/afs/slac.stanford.edu/package/netmon/pinger/pingerDB/code/pingermanagement";
my $file = "$dir/data/minrtt";
my $allfile="$dir/minrtt2";
my $version="0.6, 5/15/06, Waqar and Les";
my $url = 'http://www-iepm.slac.stanford.edu/cgi-wrap/pingtable.pl?format=tsv' ### by default , get las
. '&file=minimum_rtt&by=by-node&size=100&tick=last60days&from=WORLD'
. '&to=WORLD&ex=none&dataset=hep&percentage=any';
my $USAGE = "Function:
This script downloads the PingER data and saves it
Usage:\t $progname [opts]
Opts:
[i -allmonthly]
[-v]
Where:
allmonthly selects the URL for the input and output, the defaults are:
input URL:
$url
output file:
$file
if allmonthly is specified then the input URL is
$allurl
and the output file is
$allfile
-v provides this output.
Version: $version
";
...
require "getopts.pl";
our ($opt_i, $opt_v);
&Getopts('i:v');
if(defined($opt_v)) {print $USAGE; exit 1;}