Документ взят из кэша поисковой машины. Адрес оригинального документа : http://www.stsci.edu/ops/coding-standards.txt Дата изменения: Wed Nov 27 00:11:08 2013 Дата индексирования: Fri Feb 28 16:28:16 2014 Кодировка: Поисковые слова: ic 4603

OPB Tools Coding Standards, Styles, Version and Release Control
===============================================================
Last Modified: December 8, 2011 by Tony Roman


INTRODUCTION

This document describes the coding style and standard conventions that
will guide OPB to develop readable, maintainable, and consistent
operational tools. All OPB tools must comply to the standards and
styles set forth in this document.


STANDARDS AND CONVENTIONS

1. Languages

When selecting a language in which to write a new tool, the
developer should consider two primary factors: the functionality of
the tool and the expertise of those responsible for the future
maintenance of the tool.

A. Tool Functionality

Interpreted languages usually offer quicker and easier
development while complied languages offer much better
run-time performance for CPU-intensive applications. Also,
there are a few tasks (such as account initialization) that
can only be performed in scripts written in an operating
system language.

B. Maintainers' Expertise

OPB currently has many tools written in Tcl/Tk and in
Python. There are also a smaller number of shell scripts,
tools written in Lisp, and there is one tool written in
Java. When selecting a language for a new tool, care should
be given to keep the number of different languages within the
team's ability to effectively maintain its suite of tools.

2. File Naming

File names should be descriptive of the function or purpose of the
files. Use hyphens to separate words in the file name. Use all
lower-case letters. If a file is an executable tool, its name
should not have any extensions such as .csh, .tcl, .py. Files that
are not directly executed may have extensions in their names.

Example of Tool Names Examples of Non-Tool Names
--------------------- --------------------------
confirm-chart emacs-init.el
procheck utilities.tcl
xprint cl-init.lisp

3. File Headers

A. Interpreter line (interpreted languages only)

If the file is a tool that is written in an interpreted
language, the first line should invoke the appropriate
interpreter.

B. Emacs mode

If Emacs has a mode for the language being used, then the next
line should invoke that Emacs mode.

C. Name

The next line should be a comment that states the name of the
program. If the file is a utility package or otherwise not a
program, then just state the file name.

D. Description

Write comments to describe the purpose and functionality of the
tool or utility.

E. Revision History

Revision history comments should not be placed within the source
code. Instead, revision history comments are recorded in CVS.


Example Header
--------------

#!/usr/local/bin/tcl -f
# -*- mode:tcl -*-
#
# hello-pi
#
# Send greeting emails to new GOs at the beginning of a cycle. Use
# a user defined template containing place holder keywords to be
# replaced with program specific data from the database.
#
# IMPORTANT: These data files should be updated each cycle before
# running hello-pi:
# $env(OPS_TOOLS_DATA_DIR)/hello-pi-id-range.dat
# $env(OPS_TOOLS_DATA_DIR)/pi-email.dat
# $env(OPS_TOOLS_DATA_DIR)/pi-last-name.dat
#


4. Procedure Names and Headers

Procedures (a.k.a. subroutines, methods, functions) should be given
names that describe their functions. Procedure names should be
mixed case with each individual word in the name capitalized. There
should be no hyphens, underscores, or other punctuation between
words in procedure names. Procedure names should use a minimum of
abbreviation in order to avoid a subsequent developer having to
guess the meaning of an abbreviation. When in doubt, spell it
out. Each procedure should also begin with comments describing its
functionality.

Example
-------
proc AddUserToDistribution {distribution} {
# Add the user to an email distribution if he/she is not already included.

global env

if {![regexp $env(USER) $distribution]} {
lappend distribution $env(USER)
}

return $distribution
}


5. Variable Names

Variables should be given names that describe the data that they
store. A one word variable name should be all lower case. A
multi-word variable name should be mixed case with the first word
all in lower case and each additional word capitalized. There
should be no hyphens, underscores, or other punctuation between
words in variable names. Variable names should use a minimum of
abbreviation in order to avoid a subsequent developer having to
guess the meaning of an abbreviation. When in doubt, spell it out.

Examples
--------
directory
programList
confirmChartTargets
createproCycle
obsets
visits

6. Constant Names

Constants should be given names that describe the data that they
store. Contant names should be in upper case with individual words
separated by underscores. Constant names should use a minimum of
abbreviation in order to avoid a subsequent developer having to
guess the meaning of an abbreviation. When in doubt, spell it out.

Examples
--------
ERROR
NO
OK
YES
ALL_VISITS_FROZEN
BAD_CCL_NAME
BAD_COMMAND_LINE
BAD_INTERVAL


7. Object Oriented Programming

With the exception of one Java tool, OPB does not have any object
oriented software; so no coding standards have been developed. If
object oriented software is written in the future, coding standards
should be developed.




STYLE GUIDE

1. Comments

Source code should contain comments to enhance the overall
readability and maintainability of the code. Full English
sentences are encouraged. Introduce a segment of code by a block
comment rather than commenting every code line in the segment.
Don't delineate comment blocks with a string of "C"s, "-"s, or "*"s
(or anything); rather, use a single blank comment line to separate
code from comments. A comment block should be indented at the same
level as the code it is referencing.

Example
-------
proc ReadDefaultPrefs {} {
# Read the user preference file and set the preferences accordingly.

global env YES NO

# Define preferences and initialize them to system default values.
#
DefinePreferenceData
PropagatePreferences

# Read the user preference file. Read one line at a time. If a line begins with the user's username,
# parse it; and set the preferences accordingly.
#
set fpPref [open $env(PREFERENCES_DIR)/toolbox.preferences r]
while {![eof $fpPref]} {
gets $fpPref line
if {$line != ""} {
scan $line "%s %s %s" name variable value
if {$name == $env(USER)} {
global $variable
set $variable $value
}
}
}
close $fpPref
PropagatePreferences
}


2. Whitespace

Use a blank line to delineate code blocks and/or comments. Don't
get carried away, though; don't use more than one blank line to
separate sections.

Do NOT use whitespace inside brackets, braces, parenthesis.

Examples
--------
ham[ 1 ] (NO!)
ham[1] (YES!)

DO use one space around arithmetic and Boolean operators.

Examples
--------
i = i + 1
if i <= 3
if {$start == "" || $end == ""}

3. Indentation

Consistent indentation among code blocks is essential. For
readability purposes, indentation should be consistent from block
to block in a given tool. It is not crucial that it be consistent
from tool to tool. However, in all instances, indentation of code
blocks should be between 3 and 8 spaces. Indentations of fewer than
3 spaces makes the code difficult to read. Indentations more than 8
spaces could lead to code pushed too far to the right. Note that
Emacs has modes for most programming languages, and these modes can
indent automatically.

The code shown in the commenting example above is also an example
of good indenting.


4. Line length

Lines of code and comments should generally be limited to the size
of a line in your editor buffer, but certainly no more than 132
characters. Use line continuation symbols to continue a line of
code onto the subsequent line of the file.

Example
-------
# If a full path name has not been specified, default to the user's working directory.
#
if {![regexp $directory $phase2File] && [string range $phase2File 0 0] != "/" && [string range \
$phase2File 0 0] != "."} {
set phase2File "$directory/$phase2File"
}




VERSION CONTROL, CODE REVIEWS, AND RELEASE CONTROL

1. Version Control

CVS is to be used for version control. For instructions on using
CVS, see Version Management with CVS.

OPB's CVSROOT directory is /data/implementation/cvs.

2. Code Reviews

New tools, new utilities, and major revisions to existing code
should be reviewed by someone other than the author in order to
make sure that the new code is clearly written and documented.

Minor changes need not be reviewed in this manner.

3. Release Control

Releases to the operational environment will be performed by using
the release tool.

Usage:

release

where each item is either an entire CVS module or an indivdual file
within a particular module.

Examples:

release bin/toolbox.tcl bin/utilities.tcl
-----------------------------------------
This releases two indivdual files (toolbox.tcl and
utilities.tcl) which are both part of the CVS module bin.

release bin/gui bin/data/rdist.dat
----------------------------------
This releases the entire bin/gui CVS module, and it also
release the file rdist.dat which is part of the bin/data CVS
module.

release bin
-----------
This releases the entire bin CVS module.

4. Organization of Operational Files

All of OPB's operational tools are in /data/implementation/bin.
Subdirectories are organized as follows:

subdirectory contains
------------ --------
data configured data files
doc documentation
gui Files pertaining only to GUIs. Currently, these are
all Tcl files generated by SpecTcl.
lib Libraries of language-specific utility procedures.
source source code files for complied tools

NOTE: All program implementation tools are currently in the top
level (/data/implementation/bin). In the future, it may make
sense to move these tools to their own subdirectory.