Rules for Programmers in Python

We have collected a set of rules and laws that apply to writing code, based on his experience of having written tens of thousands of lines of code and 45 years as a programmer. There are over 250 of them, but not all apply to Python. For example, Python enforces indenting and has no begin-end symbols. The ones that do apply are as follows:

  1. Use four-space indents and not tabs.
  2. Place a comment in lieu of a declaration for all variables in languages where declarations are not permitted.
  3. Declare numeric constants and provide a comment explaining them.
  4. Rarely use a numeric constant in an expression; name and declare them.
  5. Use variable names that refer to the use or meaning of the variable.
  6. Make your code clean from the beginning, not after it works.
  7. A non-working program is useless, no matter how well structured.
  8. Write code that is as general as possible, even if that makes it longer.
  9. If the code you write is general, then keep it and reuse it when appropri­ate.
  10. Functions longer than 12 (not including declarations) lines are suspect.
  11. Avoid recursion wherever possible.
  12. Every procedure and function must have comments explaining function and use.
  13. Write external documentation as you code—every procedure and func­tion must have a description in that document.
  14. Some documentation is for programmers, and some is for users. Distin­guish.
  15. Documentation for users must never be in the code.
  16. Avoid using operating system calls.
  17. Avoid using machine-dependent techniques.
  18. Do use the programming language library functions.
  19. Documentation for a procedure includes what other procedures are called.
  20. Documentation for a procedure includes what procedures might call it.
  21. When doing input: assume that the input file is wrong.
  22. Your program should accept ANY input without crashing. Feed it an executable as a test.
  23. Side effects are very bad. A proper function should return a value that depends only on its parameters. Exceptions do exist and should be docu­mented.
  24. Everything not defined is undefined.
  25. Buffers and strings have fixed sizes. Know what they are and be con­strained by them.
  26. A handle is a pointer to a structure for an object; make certain that han­dles used are still valid.
  27. Strings and buffers should not overlap in storage.
  28. Contents of strings and buffers are undefined until written to.
  29. Every variable that is declared is to be given a value before it is used.
  30. Put some blank lines between method definitions.
  31. Explain each declared variable in a comment.
  32. Solve the problem requested, not the general case or subsets.
  33. White space is one of the most effective comments.
  34. Avoid global symbols where possible; use them properly where useful.
  35. Avoid casts (type casting).
  36. Round explicitly when rounding is needed.
  37. Always check the error return codes.
  38. Leave spaces around operators such as =, ==, and !=.
  39. A method should have a clear, single, identifiable task.
  40. A class should represent a clear, single, identifiable concept.
  41. Do the comments first.
  42. A function should have only one exit point.
  43. Read the code.
  44. Comments should be sentences.
  45. A comment shouldn’t re-state the obvious.
  46. Comments should align.
  47. Don’t confuse familiarity with readability.
  48. A function should be called more than once.
  49. Code used more than once should be put into a function.
  50. All code should be printable.
  51. Don’t write very long lines (no more than 80 characters).
  52. The function name must agree with what the function does.
  53. Format programs in a consistent manner.
  54. Have a log.
  55. Document all the principal data structures.
  56. Don’t print a message for a recoverable error—log it.
  57. Don’t use system-dependent functions for error messages.
  58. You must always correctly attribute all code in the module header.
  59. Provide cross references in the code to any documents relevant to the understanding of the code.
  60. All errors should be listed together with an English description of what they mean.
  61. An error message should tell the user the correct way to do it.
  62. Comments should be clear and concise and avoid unnecessary wordi­ness.
  63. Spelling counts.
  64. Run your code through a spelling checker.
  65. Function documentation includes the domain of valid inputs to the func­tion.
  66. Function documentation includes the range of valid outputs from the function.
  67. Each file must start with a short description of the module contained in the file and a brief description of all exported functions.
  68. Do not comment out old code—remove it.
  69. Use a source code control system.
  70. Comments should never be used to explain the language.
  71. Don’t put more than one statement on a line.
  72. Never blindly make changes to code trying to remove an error.
  73. Printing variable values in key places can help you find the location of a bug.
  74. One compilation error can hide scores of others.
  75. If you can’t seem to solve a problem, then do something else.
  76. Explain it to the duck. Get an inanimate object and explain your problem to it. This often solves it. (Wyvill)
  77. Don’t confuse ease of learning with ease of use.
  78. A program should be written at least twice—throw away the first one.
  79. Haste is not speed.
  80. You can’t measure productivity by volume.
  81. Expect to spend more time in design and less in development
  82. You can’t program in isolation.
  83. If an if ends in return, don’t use else.
  84. Avoid operator overloading.
  85. Scores of compilation errors can sometimes be fixed with one character— start at the first one.
  86. Programs that compile mostly still do not work.
  87. Incrementally refine your code. Start with BEGIN-SOLVE-END, then refine SOLVE.
  88. Draw diagrams of data and algorithms.
  89. Use a symbolic debugger wherever possible.
  90. Make certain that files have the correct name (and suffix!) when open­ing.
  91. Never assign a value in a conditional expression.
  92. If you can’t say it in English, you can’t say it in any programming lan­guage.
  93. Don’t move language idioms from one language to another.
  94. Do no harm.
  95. If the program is object oriented, design the objects first.
  96. Don’t write deeply nested code.
  97. Multiple inheritance is evil. Avoid this sin.
  98. Productivity can be measured in the number of keystrokes (sometimes).
  99. Your code is not perfect. Not even close. Have no ego about it.
  100. Variables are to be declared with the smallest possible scope.
  101. The names of variables and functions should begin with a lowercase letter.
  102. Collect your best working modules into a code library.
  103. Isolate dirty code (e.g., code that accesses machine dependencies) into distinct and carefully annotated modules.
  104. Anything you assume about the user will eventually be wrong.
  105. Every time a rule is broken, this must be clearly documented.
  106. Write code for the next programmer, not for the computer.
  107. Your program should always degrade gracefully.
  108. Don’t surprise your user.
  109. Involve users in the development process.
  110. Most programs should run the same way and give the same results each time they are executed.
  111. Most of your code will be checking for errors and potential errors.
  112. Normal code and error handling code should be distinct.
  113. Don’t write very large modules.
  114. Put the shortest clause of an if/else on top.
  115. Have a library of error-reporting code and use it (be consistent).
  116. Report errors in a way that they make sense.
  117. Report errors in a way that allows them to be corrected.
  118. Only fools think they can optimize code better than a good compiler.
  119. Change the algorithm, not the code, to make things faster. A polynomial is a polynomial.
  120. Copying and pasting is only for prototypes.
  121. It’s always your fault.
  122. Know what the problem is before you start coding.
  123. Don’t re-invent the wheel.
  124. Keep things as simple as possible.
  125. Data structures, not algorithms, are central to programming. (Pike)
  126. Learn from your mistakes.
  127. Learn from the mistakes of others.
  128. First make it work, then make it work faster.
  129. We almost never need to make it faster.
  130. First make it work, then make it work better.
  131. Programmers don’t get to make big design decisions—do what is asked, effectively.
  132. Learn new languages and techniques when you can.
  133. Never start a new project in a language you don’t already know.
  134. You can learn a new language effectively by coding something signifi­cant in it, just don’t expect to sell the result.
  135. You will always know only a subset of any given language.
  136. The subset you know will not be the same as the subset your co-workers know.
  137. Object orientation is not the only way to do things.
  138. Object orientation is not always the best way to do things.
  139. To create a decent object, one first needs to be a programmer.
  140. You may be smarter than the previous programmer, but leave their code alone unless it is broken.
  141. You probably are not smarter than the previous programmer, so leave their code alone unless it is broken.
  1. Your program will never actually be complete. Live with it.
  2. All functions have preconditions for their correct use.
  3. Sometimes a function cannot tell whether its preconditions are true.
  4. Computers have gigabytes of memory, mostly. Optimizing it is the last thing to do.
  1. Compute important values in two different ways and compare them.
  2. 1 * 10 is not equal to 1.
  3. Adding manpower to a late software project makes it later.
  4. It always takes longer than you expect.
  5. If it can be null, it will be null.
  6. Do not use catch and throw unless you know exactly what you are doing (be careful with exception handling).
  7. Be clear about your intention. i=1-i is not the same as if(i==0) then i=1 else i=0.
  8. Fancy algorithms are buggier than simple ones, and they’re much harder to implement. (Pike)
  9. The first 90% of the code takes 10% of the time. The remaining 10% takes the other 90% of the time.
  1. All messages should be tagged.
  2. Do not use FOR loops as time delays.
  3. A user interface should not look like a computer program.
  4. Decompose complex problems into smaller tasks.
  5. Use the appropriate language for the job, when given a choice.
  6. Know the size of the standard data types.
  7. If you simultaneously hit two keys on the keyboard, the one that you do not want will appear on the screen.
  8. Patterns are for the weak—it assumes you don’t know what you are doing.
  9. Don’t assume precedence rules, especially when debugging—parenthe­size.
  1. Do not use ++ and –. Use code like i = i + 1.
  2. It’s hard to see where a program spends most of its time.
  3. Fancy algorithms are slow when n is small, and n is usually small. (Pike)
  4. Assume that things will go wrong.
  5. Computers don’t know any math.
  6. Expect the impossible.
  7. Test everything. Test often.
  8. Do the simple bits first.
  9. Don’t fix what is not broken.
  10. If it is not broken, then try to break it.
  11. Don’t draw conclusions based on names.
  12. A carelessly planned project takes three times longer to complete than expected; a carefully planned project takes only twice as long.
  13. Any system that depends on human reliability is unreliable.
  14. The effort required to correct course increases geometrically with time.
  15. Complex problems have simple, easy to understand, and wrong answers.
  16. An expert is that person most surprised by the latest evidence to the con­trary.
  17. One man’s error is another man’s data.
  18. Noise is something in data that you don’t want. Someone does want it.

Source: Parker James R. (2021), Python: An Introduction to Programming, Mercury Learning and Information; Second edition.

Leave a Reply

Your email address will not be published. Required fields are marked *