Or, How not to write programs

---

Do not make any of the following mistakes in any program you ever write.

 

Use excellent variable and function names (not bad ones)

---

Here is a list of bad variable names:

1. Ambiguous:
1. $type  # better: $type_of_event
2. $id  # better: $person_id
3. $input  # better: $str_with_commas (I've seen $input a lot in functions such as remove_commas($input).)
2. Ambiguous prefixes:
1. $p_type   # better: $person_type
3. Super-short (except for "throw-aways"):
1. $r  # better: $registration_type
4. Variable names only indicating the type of variable:
1. $str, $string  # better: str_of_user_id
2. $int, $integer, $num, $number, $decimal
3. $list, $collection, 

 

Here is a list of bad function names:

1. dow()  # This actually returned the Day Of Week.  Why not use day_of_week()?  Were you running out of characters?
2. multivalue()  # Multivalue what?

 

Include great documentation (don't forget to include it and don't write useless documentation)

---

Include documentation.  Document the following.

 

1) Required function inputs and expected function outputs

2) Why non-variable constants are used:

if(person_type == "R"):  # should be doc'ed with --> "R" is for "really cool"

 

3) Why an else condition has been met

Else conditions can be confusing, because you can't tell just from looking at one why it has been met.  They are convenient for writing code, but inconvenient for reading code  (which takes a much larger fraction of your overall time, on average, than writing code).

 

Bad:

     #...

     }

else

     {

     print "You are all out of luck."

     print "It didn't work at all."

     print "Nuts, eh?"

     }

 

Better:

     #...

     }

else

     # We are here because the user failed to enter required data.

     {

 

As long as we have the else condition documented, we can fix the logic.  Perhaps the original "if" or subsequent "elif" statements fail to ensure that the else will cover only the conditions that the documentation says should be covered by it--and that's OK because we can rectify the code to conform with the intent.  But without the doc, we can't fix anything without serious time spent debugging.

 

 

3) Incomplete documentation

Document things more completely.  For example, consider the following:

 

Not great:

     #...

     }

else

     # We are here because the user failed to enter required data.

     {

 

Greater:

     #...

     }

else

     # The user failed to enter required data; print a warning message (so he knows that there was a failure).

     {

 

As shown above, I highly prefer this style of control statement documentation: <The reason you are here>; <what we should do because we are here> (<why <the reason you are here> justifies <what we should do because we are here>).

 

4) Comment above code folds and indent code with control statements

Bad:

else

     {

     # The user failed to enter required data; print a warning message (so he knows that there was a failure).

     print "This is something to print as an example."; 

     # ...

     # ...

     # ...

     }

 

Because it will fold to this:

 

else

     -{...}

 

Better:

else

     # The user failed to enter required data; print a warning message (so he knows that there was a failure).

      {

     print "This is something to print as an example.";

     # ...

     # ...

     # ...

     }

 

Because it will fold to this:

else

     # The user failed to enter required data; print a warning message (so he knows that there was a failure).

     -{...}

     

This  second method (above the fold) of commenting allows the programmer to read the entire flow of control in a program without having to scroll through the code.

 

Note also how comments are indented to the same level that the code that gets executed if the control statement is met is indented:

 

Bad:

# The user failed to enter required data; print a warning message (so he knows that there was a failure).

else

     {

     print "This is something to print as an example."; 

     }

 

Better:

else

     # The user failed to enter required data; print a warning message (so he knows that there was a failure).

     {

     print "This is something to print as an example."; 

     }

 

The second method is better because the comment is only true when the control statement is met, and indentation should always indicate control/scope.

 

5) Don't just document what the code does; document why the code does what it does and what you expect from the code.

 

Bad:

print "$the_answer + $random_number"  # Prints the answer plus a random number

 

Better:

print "$the_answer + $random_number"  # Vary the answer by +/- 0.2 to make things look "natural" to the user

 

6) Document what you haven't done or what you don't understand

Use the easily findable string "TODO:" when you need to complete something.

 

---

Home  |  Up  |  Copyleft  |  Contact