Labbooks: Essential.
( in 
Coding Style and Good Computing Practices by 
Jonathan Nagler)
- Command Files: they should be kept.
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Know the goal of the code
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Fixing Mistakes
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Data-Manipulation vs. Data-Analysis: these should be in distinct files.
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Keep Tasks Compartmentalized (`modularity').
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Know what the code is supposed to do before you start.
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Don't be Too Clever.
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Variable Names should mean something.
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Use parentheses and white-space to make code readable.
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Documentation: All code should include
comments meaningful to others.
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Recodes and creating new variables
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Procedures or macro
( in Coding Style and Good Computing Practices by Jonathan Nagler)
- Maintain a labbook from the beginning of a project to
the end.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Code each variable so that it corresponds as closely as possible to
a verbal description of the substantive hypothesis the variable will be
used to test.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Errors in code should be corrected where they occur and
the code re-run.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Separate tasks related to data-manipulation
vs data-analysis into separate files.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Each program should perform only one task.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Do not try to be as clever as possible when coding. Try to
write code that is as simple as possible.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Each section of a program should perform only one task.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Use a consistent style regarding lower and upper case letters.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Use variable names that have substantive meaning.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Use variable names that indicate direction where possible.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Use appropriate white-space in your programs, and do so
in a consistent fashion to make them easy to read.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Include comments before each block of code describing
the purpose of the code.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Include comments for any line of code if the meaning
of the line will not be unambiguous to someone other than yourself.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Rewrite any code that is not clear.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- Verify that missing data is handled correctly on any
recode or creation of a new variable.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- After
creating each new variable or recoding any variable, produce frequencies
or descriptive statistics of the new variable and examine them to be
sure that you achieved what you intended.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
- When possible, automate things and avoid placing hard-wired
values (those computed `by-hand') in code.
( rule proposed in Coding Style and Good Computing Practices by Jonathan Nagler)
-
Use full English descriptors that accurately describe the variable/field/class/… For example, use
names like firstName, grandTotal, or CorporateCustomer. Although names like x1, y1, or fn are
easy to type because they're short, they don't provide any indication of what they represent and result
in code that is difficult to understand, maintain, and enhance (
in Coding Style and Good Computing Practices by Jonathan Nagler
).
(quoted from
1.3 WHAT MAKES UP A GOOD NAME in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 1
)
-
Comments should add to the clarity of your code. The reason why you document your code is to
make it more understandable to you, your coworkers, and to any other developer who comes after you
(
in Coding Style and Good Computing Practices by Jonathan Nagler
).
(quoted from
1.4.1 The Three Types of Java Comments in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 3
)
-
If your program isn't worth documenting, it probably isn't worth running (
in Coding Style and Good Computing Practices by Jonathan Nagler
). What
can I say, Nagler hit the nail on the head with this one.
(quoted in: 1.4.2 A Quick Overview of javadoc in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 4)
-
Remember, if your code isn't worth documenting then it isn't worth keeping (
in Coding Style and Good Computing Practices by Jonathan Nagler
). When you
apply the documentation standards and guidelines proposed in this paper appropriately you can greatly
enhance the quality of your code.
(quoted from
2.4 TECHNIQUES FOR WRITING CLEAN CODE 2.4.1 Document Your Code in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 10
)
-
A really easy way to improve the understandability of your code is to use parenthesis, also called "round
brackets," to specify the exact order of operations in your Java code (
in Coding Style and Good Computing Practices by Jonathan Nagler
). If I
have to know the order of operations for a language to understand your source code then something is
seriously wrong. This is mostly an issue for logical comparisons where you AND and OR several other
comparisons together. Note that if you use short, single command lines as suggested above then this
really shouldn't crop up as an issue.
(quoted from
2.4 TECHNIQUES FOR WRITING CLEAN CODE 2.4.6 Specify the Order of Operations in AmbySoft Inc. Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 11:
)