Differences

This shows you the differences between two versions of the page.

--- sudoc:su_prog_rules [2019/07/30 21:18] – [Develop from existing code] seisunix
+++ sudoc:su_prog_rules [2019/07/30 21:55] (current) – seisunix
@@ Line 8: / Line 8: @@
 The first of these is that **changing the SU header definitions is forbidden.** The header structure looks deceptively simple, but contains a hidden trap, that it is possible to easily introduce a gap in the header that would render the SU data made under a new system mutually incompatible with that made by other versions of SU.
+Suppose, however, you need another header field? The way to approach this is to use one of the less commonly used fields, define a keyword field so that the user may change this.
 ===== Avoid mix-language programming =====
@@ Line 18: / Line 20: @@
 The reality is that the more items that a user must fetch to install your code, the less likely that they will want to use it. You will also be at the mercy of whims of third party developers who may decide arbitrarily to change their code.
 ===== Do not include commercial software =====
 There are a number of "open" packages, such as Numerical Recipes, that are commercial packages, but are not really open source. It is forbidden to introduce such code into the SU collection.
-===== Be conscious of the open source license =====
+===== Be conscious of the open source licenses =====
 The SU materials are released under a Berkeley-style open source license. This choice avoids the viral aspect of the GNU Public License. Commercial developers may think twice about making use of GPL Licensed items, because of the requirement that improvements must be returned to the originators of code, and that derivative code automatically inherits the GPL License.
 The limitation is that while code released under a Berkeley License may be absorbed into a GPL software collection, the reverse is not true. You may not include GPL licensed code in the SU distribution.
+===== Avoid using global variables =====
+If you need to pass a variable to a subroutine then pass it as an argument to the subroutine, do not define it as a global variable.
+===== Document your code thoroughly =====
+Make sure there are Notes: in the Self Documentation.
+Document each declared variable. Put technical information describing the algorithm being used. Remember that "future you" will not remember the things that "present you" knows.
+Document subroutines as though they will be clipped out and put in a library---because if a subroutine is useful, it will be separated from its parent program.
+Pretend that the code will not run without the documentation.
 ===== Develop from existing code ====
-An example program is **sufiler.c**
+An example program is **sufiler.c** which is located in **$CWPROOT/src/su/main/filters**
+Proceeding block by block in the code,
+**The copyright statement **
 <code>
 /* Copyright (c) Colorado School of Mines, 2011.*/
-/* All rights reserved.                       */
+/* All rights reserved.        */
+</code>
+**The RCS (revision control system) version label **
+<code>
 /* SUFILTER: $Revision: 1.23 $ ; $Date: 2011/11/12 00:09:00 $        */
+</code>
+**The include files that define the SU data type**
+<code>
 #include "su.h"
 #include "segy.h"
+</code>
+** The begin selfdoc flag which allows updated to capture the self documentation for tools such as suname **
+<code>
 /*********************** self documentation **********************/
+</code>
+**The self documentation **
+<code>
 char *sdoc[] = {
 "                                                                       ",
@@ Line 69: / Line 99: @@
 " Notch:      sufilter <data f=10,12.5,35,50,60 amps=1.,.5,0.,.5,1. |.. ",
 NULL};
+</code>
+**The attribution block, authors, technical references, and header fields and other technical details go here**
+<code>
 /* Credits:
  *      CWP: John Stockwell, Jack Cohen
@@ Line 79: / Line 112: @@
  * Trace header fields accessed: ns, dt, d1
  */
+</code>
+** The end self documentation flag, this tells updatedoc that this is the end of the documentation**
+<code>
 /**************** end self doc ***********************************/
+</code>
+**Function prototypes**
+<code>
 /* Prototype of function used internally */
 void polygonalFilter(float *f, float *amps,
                         int npoly, int nfft, float dt, float *filter);
+</code>
+**internally defined constants**
+<code>
 #define PIBY2   1.57079632679490
 #define FRAC0   0.10    /* Ratio of default f1 to Nyquist */
@@ Line 92: / Line 135: @@
 #define LOOKFAC 2       /* Look ahead factor for npfao    */
 #define PFA_MAX 720720  /* Largest allowed nfft           */
+</code>
+**Declaration of SEGY type objects in global space.**
+<code>
 segy tr;
+</code>
+** The main **
+<code>
 int
 main(int argc, char **argv)
 {
+</code>
+** Declarations **
+<code>
         register float *rt;     /* real trace                           */
         register complex *ct;   /* complex transformed trace            */
@@ Line 114: / Line 166: @@
         int verbose;            /* flag to get advisory messages        */
         cwp_Bool seismic;       /* is this seismic data?                */
+</code>
+** Initialize the command line, or output selfdoc **
+<code>
         /* Initialize */
         initargs(argc, argv);
         requestdoc(1);
+</code>
+** Get parameters from the first trace and from the command line**
+<code>
         /* Get info from first trace */
         if (!getparint("verbose", &verbose))    verbose=0;
@@ Line 147: / Line 203: @@
         nt = tr.ns;
         nyq = 0.5/dt;
+</code>
+** read trace by trace and perform the filtering **
+<code>
         /* Set up FFT parameters */
         nfft = npfaro(nt, LOOKFAC * nt);
@@ Line 203: / Line 262: @@
         }
         if (icount==0) warn("All amps values are the same");
+</code>
+** Dynamic allocation which hides "malloc" from the user **
+<code>
         /* Allocate fft arrays */
@@ Line 213: / Line 275: @@
         polygonalFilter(f,amps,npoly,nfft,dt,filter);
+</code>
+** note that most of the time we loop over input traces, these are in  "do -- while" loops **
+<code>
         /* Main loop over traces */
         do {
@@ Line 235: / Line 301: @@
 }
+</code>
+** Definition of the subroutine that builds the filter **
+<code>
 void polygonalFilter(float *f, float *amps, int npoly,
                                 int nfft, float dt, float *filter)