Differences

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

--- sudoc:su_prog_rules [2019/07/30 21:34] – 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 ====
@@ Line 87: / Line 101: @@
 </code>
-**The attribution block **
+**The attribution block, authors, technical references, and header fields and other technical details go here**
 <code>
 /* Credits:
@@ Line 100: / Line 114: @@
 </code>
-** The end self documentation flag **
+** The end self documentation flag, this tells updatedoc that this is the end of the documentation**
 <code>
 /**************** end self doc ***********************************/
@@ Line 123: / Line 137: @@
 </code>
-**Declaration of SEGY type objects in global space**
+**Declaration of SEGY type objects in global space.**
 <code>
 segy tr;
@@ Line 248: / 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 258: / 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 {