Skip to content

Commit 913d3eb

Browse files
znorman-harrisznorman-harris
committed
Initial commit.
1 parent 00ad745 commit 913d3eb

File tree

1 file changed

+188
-2
lines changed

1 file changed

+188
-2
lines changed

‎README.md

Lines changed: 188 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,188 @@
1-
# contrib-guide
2-
Short guide for how contributed code should be written so that the formats are all consistent.
1+
# Guide for Contributing Code
2+
3+
The purpose of this guide is to set some standards for how anyone can write IDL code and contribute to repositories for IDL and ENVI. These are meant as guidelines and some of the formatting requests below are not required, but they will help everything be consistent and easier for beginners to follow along with.
4+
5+
In general, the rule is to write code **with readability in mind** so that others can easily understand what you are doing and be able to follow your logic. The first and most important piece of that is comments!
6+
7+
8+
## Comments
9+
10+
Comments are a critical part of any programming project especially when users that are not as advanced might be using the code. Please do your best to comment everywhere and make it clear what you are doing.
11+
12+
### General Comments
13+
14+
To make sure that it is clear to any users what any code is doing, it is important to frequently comment your code. Typically this should look like a few words for each chunk of code that is written. Here is an example:
15+
16+
```
17+
;check for bad data values
18+
idx = where(someArr eq 0, countArr)
19+
if (countArr gt 0) then begin
20+
;remove bad values from data
21+
someArr[idx] = 1
22+
endif
23+
24+
;save the data to disk
25+
openw, lun, file, /GET_LUN
26+
printf, lun, someArr
27+
free_lun, lun
28+
```
29+
30+
Note that for experienced programmers the steps may be apparent, but new programmers might not understand all that the code is doing. Plenty of comments make it easy for everyone to understand the code so that it can be re-used in other places.
31+
32+
33+
### Routine Comments
34+
35+
When using the IDL workbench, you can very easily add a comment template for any selected routine. To do so, you simply need to: save your work, highlight the name of the function or procedure, right click, and select add routine comments.
36+
37+
For this, IDL will add a template for comments with the arguments and keywords already started for you. When filling out the parameter description, you should use follow the format:
38+
39+
```
40+
;+
41+
; :Description:
42+
; This function/procedure does blah.
43+
;
44+
; :Params:
45+
; some_param: direction, required, type=IDL_Type
46+
; This parameter does blah.
47+
;
48+
; :Keywords:
49+
; SOME_KEYWORD: direction, required, type=IDL_Type, default=defaultValue
50+
; Some short description of what the keyword does.
51+
;
52+
; :Author: Zachary Norman - Github: znorman17
53+
;
54+
;-
55+
```
56+
57+
Where the values represent:
58+
59+
- The direction of the keyword/argument (i.e. input or output)
60+
61+
- Whether the parameter needs to be provided or not
62+
63+
- The data type that is expected (i.e float, double, structure, ENVIRaster)
64+
65+
- If relevant, the default value for the parameter. Not a required addition.
66+
67+
The format for the keywords above follows that of IDL doc (a neat package developed by Mike Galloy).
68+
69+
70+
### Header Comments (optional)
71+
72+
In addition to adding comments for each separate routine you should also add an overall comment section to the top of each PRO code file. This should just have a basic description of the contents of the file and possibly a short example for how to run the routine.
73+
74+
If you do not add comments at the beginning of each file, then just make sure that there is a place somewhere that describes the purpose of the code that is easy to find.
75+
76+
77+
78+
## Naming Conventions and Formatting
79+
80+
Here are some general rules to follow for how syntax should be formatted.
81+
82+
83+
### Generic Variables
84+
85+
Underscores or camel case are each acceptable. Try to make names descriptive and have a short comment when the variable is created describing what it is for. For example:
86+
87+
```
88+
;flag for type of processing being performed
89+
datFlag = 1
90+
```
91+
92+
93+
### Procedures and Functions
94+
95+
The names of routines can have underscores and be camel case.
96+
97+
The most important routine in the PRO code **MUST** be at the bottom of the file and have the same name as the PRO file. In other words, a file called "some_routine.pro" should have a procedure or function called "some_routine" as the last routine in the file.
98+
99+
The file name should **ALWAYS** be lower case (important for non-Windows operating systems). The routine name in the PRO code can have capital letters.
100+
101+
When you have multiple routines that are all used for the same PRO code, then the naming convention should be similar to the following example (to make sure there are no name space issues in IDL). For example, I have a PRO code file called "awesome_classification.pro" and my routines are named (in order from the top to the bottom of the file):
102+
103+
```
104+
awesome_classification_calculateValues
105+
awesome_classification_preprocessData
106+
awesome_classification
107+
```
108+
109+
While this makes the routine names be a little bit longer, they will be more descriptive as to where they come from and they will make sure that there are no collisions with file naming.
110+
111+
112+
113+
### Keywords
114+
115+
**ALL** keywords should be written such that the left hand side and the right hand side have the same name. For beginner programmers this concept can be challenging so it helps things be easier to understand.
116+
117+
The keywords should also be capitalized on the left and lower case (or camel case) on the right. Here is an example of how you should define them:
118+
119+
```
120+
pro someProcedure, FIRST_KEYWORD = first_keyword, SECOND_KEYWORD = second_keyword
121+
compile_opt idl2
122+
;do something...
123+
end
124+
```
125+
126+
Here is an example of how you should would format the call to this procedure when using it:
127+
128+
```
129+
someProcedure, FIRST_KEYWORD = fooBar, SECOND_KEYWORD = 42
130+
```
131+
132+
If your keywords are for outputs, then name them appropriately such as:
133+
134+
```
135+
pro someProcedure, FIRST_KEYWORD = first_keyword, OUTPUT_DATA = output_data
136+
compile_opt idl2
137+
;do something...
138+
end
139+
```
140+
141+
### Arguments
142+
143+
Don't use arguments for returning results, instead use keywords. Arguments should **ONLY** be used for required information that is needed for a function or procedure and not for optional information.
144+
145+
146+
### Keywords vs Arguments
147+
148+
Similar to functions and procedures, keywords and arguments can be used interchangeably. The rule of thumb is that arguments are **ONLY** for required inputs and **NOT** outputs. Keywords are traditionally for optional inputs and additional outputs, but can also be used for inputs to routines.
149+
150+
This is also based on personal preference and the type of code that is being developed. For example, if you are writing a task for ENVI or IDL, then all of your parameters need to be used as keywords so this may be easier (and habit) when writing code. This is just fine as long as it makes sense what the code is doing.
151+
152+
153+
## Control Statements
154+
155+
In IDL the control statements (i.e. if, for, while) should all be written as multi-line statements to make them easier to read. This means that they should be written in the form:
156+
157+
```
158+
if (this eq 1) then begin
159+
;do something
160+
endif
161+
```
162+
163+
Some exceptions are if you have a simple statement such as:
164+
165+
```
166+
if (1 eq var) then continue
167+
```
168+
169+
This does not need a multi-line code block because it is easy to read as is.
170+
171+
172+
## Functions vs. Procedures
173+
174+
Because IDL has two different types of routines (i.e. functions and procedures), there are different times when it is appropriate to use one over the other. However, this is also based on personal preference so just think about if it would be easy for others to understand your code or not.
175+
176+
The general rule is that functions are used when you are returning values and procedures are not. **However**, if more than one variable needs to be returned then procedures are a great alternative with multiple keywords.
177+
178+
179+
## Compile-opt idl2
180+
181+
Every routine **MUST** have ```compile_opt idl2``` at the beginning of each procedure or function. It forces programmers to use square brackets for indexing arrays and changes the default data type to long instead of unsigned integer. For example this would look like:
182+
183+
```
184+
pro someProcedure, FIRST_KEYWORD = first_keyword, SECOND_KEYWORD = second_keyword
185+
compile_opt idl2
186+
;do something...
187+
end
188+
```

0 commit comments

Comments
 (0)