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:
- Use four-space indents and not tabs.
- Place a comment in lieu of a declaration for all variables in languages where declarations are not permitted.
- Declare numeric constants and provide a comment explaining them.
- Rarely use a numeric constant in an expression; name and declare them.
- Use variable names that refer to the use or meaning of the variable.
- Make your code clean from the beginning, not after it works.
- A non-working program is useless, no matter how well structured.
- Write code that is as general as possible, even if that makes it longer.
- If the code you write is general, then keep it and reuse it when appropriate.
- Functions longer than 12 (not including declarations) lines are suspect.
- Avoid recursion wherever possible.
- Every procedure and function must have comments explaining function and use.
- Write external documentation as you code—every procedure and function must have a description in that document.
- Some documentation is for programmers, and some is for users. Distinguish.
- Documentation for users must never be in the code.
- Avoid using operating system calls.
- Avoid using machine-dependent techniques.
- Do use the programming language library functions.
- Documentation for a procedure includes what other procedures are called.
- Documentation for a procedure includes what procedures might call it.
- When doing input: assume that the input file is wrong.
- Your program should accept ANY input without crashing. Feed it an executable as a test.
- Side effects are very bad. A proper function should return a value that depends only on its parameters. Exceptions do exist and should be documented.
- Everything not defined is undefined.
- Buffers and strings have fixed sizes. Know what they are and be constrained by them.
- A handle is a pointer to a structure for an object; make certain that handles used are still valid.
- Strings and buffers should not overlap in storage.
- Contents of strings and buffers are undefined until written to.
- Every variable that is declared is to be given a value before it is used.
- Put some blank lines between method definitions.
- Explain each declared variable in a comment.
- Solve the problem requested, not the general case or subsets.
- White space is one of the most effective comments.
- Avoid global symbols where possible; use them properly where useful.
- Avoid casts (type casting).
- Round explicitly when rounding is needed.
- Always check the error return codes.
- Leave spaces around operators such as =, ==, and !=.
- A method should have a clear, single, identifiable task.
- A class should represent a clear, single, identifiable concept.
- Do the comments first.
- A function should have only one exit point.
- Read the code.
- Comments should be sentences.
- A comment shouldn’t re-state the obvious.
- Comments should align.
- Don’t confuse familiarity with readability.
- A function should be called more than once.
- Code used more than once should be put into a function.
- All code should be printable.
- Don’t write very long lines (no more than 80 characters).
- The function name must agree with what the function does.
- Format programs in a consistent manner.
- Have a log.
- Document all the principal data structures.
- Don’t print a message for a recoverable error—log it.
- Don’t use system-dependent functions for error messages.
- You must always correctly attribute all code in the module header.
- Provide cross references in the code to any documents relevant to the understanding of the code.
- All errors should be listed together with an English description of what they mean.
- An error message should tell the user the correct way to do it.
- Comments should be clear and concise and avoid unnecessary wordiness.
- Spelling counts.
- Run your code through a spelling checker.
- Function documentation includes the domain of valid inputs to the function.
- Function documentation includes the range of valid outputs from the function.
- Each file must start with a short description of the module contained in the file and a brief description of all exported functions.
- Do not comment out old code—remove it.
- Use a source code control system.
- Comments should never be used to explain the language.
- Don’t put more than one statement on a line.
- Never blindly make changes to code trying to remove an error.
- Printing variable values in key places can help you find the location of a bug.
- One compilation error can hide scores of others.
- If you can’t seem to solve a problem, then do something else.
- Explain it to the duck. Get an inanimate object and explain your problem to it. This often solves it. (Wyvill)
- Don’t confuse ease of learning with ease of use.
- A program should be written at least twice—throw away the first one.
- Haste is not speed.
- You can’t measure productivity by volume.
- Expect to spend more time in design and less in development
- You can’t program in isolation.
- If an if ends in return, don’t use else.
- Avoid operator overloading.
- Scores of compilation errors can sometimes be fixed with one character— start at the first one.
- Programs that compile mostly still do not work.
- Incrementally refine your code. Start with BEGIN-SOLVE-END, then refine SOLVE.
- Draw diagrams of data and algorithms.
- Use a symbolic debugger wherever possible.
- Make certain that files have the correct name (and suffix!) when opening.
- Never assign a value in a conditional expression.
- If you can’t say it in English, you can’t say it in any programming language.
- Don’t move language idioms from one language to another.
- Do no harm.
- If the program is object oriented, design the objects first.
- Don’t write deeply nested code.
- Multiple inheritance is evil. Avoid this sin.
- Productivity can be measured in the number of keystrokes (sometimes).
- Your code is not perfect. Not even close. Have no ego about it.
- Variables are to be declared with the smallest possible scope.
- The names of variables and functions should begin with a lowercase letter.
- Collect your best working modules into a code library.
- Isolate dirty code (e.g., code that accesses machine dependencies) into distinct and carefully annotated modules.
- Anything you assume about the user will eventually be wrong.
- Every time a rule is broken, this must be clearly documented.
- Write code for the next programmer, not for the computer.
- Your program should always degrade gracefully.
- Don’t surprise your user.
- Involve users in the development process.
- Most programs should run the same way and give the same results each time they are executed.
- Most of your code will be checking for errors and potential errors.
- Normal code and error handling code should be distinct.
- Don’t write very large modules.
- Put the shortest clause of an if/else on top.
- Have a library of error-reporting code and use it (be consistent).
- Report errors in a way that they make sense.
- Report errors in a way that allows them to be corrected.
- Only fools think they can optimize code better than a good compiler.
- Change the algorithm, not the code, to make things faster. A polynomial is a polynomial.
- Copying and pasting is only for prototypes.
- It’s always your fault.
- Know what the problem is before you start coding.
- Don’t re-invent the wheel.
- Keep things as simple as possible.
- Data structures, not algorithms, are central to programming. (Pike)
- Learn from your mistakes.
- Learn from the mistakes of others.
- First make it work, then make it work faster.
- We almost never need to make it faster.
- First make it work, then make it work better.
- Programmers don’t get to make big design decisions—do what is asked, effectively.
- Learn new languages and techniques when you can.
- Never start a new project in a language you don’t already know.
- You can learn a new language effectively by coding something significant in it, just don’t expect to sell the result.
- You will always know only a subset of any given language.
- The subset you know will not be the same as the subset your co-workers know.
- Object orientation is not the only way to do things.
- Object orientation is not always the best way to do things.
- To create a decent object, one first needs to be a programmer.
- You may be smarter than the previous programmer, but leave their code alone unless it is broken.
- You probably are not smarter than the previous programmer, so leave their code alone unless it is broken.
- Your program will never actually be complete. Live with it.
- All functions have preconditions for their correct use.
- Sometimes a function cannot tell whether its preconditions are true.
- Computers have gigabytes of memory, mostly. Optimizing it is the last thing to do.
- Compute important values in two different ways and compare them.
- 1 * 10 is not equal to 1.
- Adding manpower to a late software project makes it later.
- It always takes longer than you expect.
- If it can be null, it will be null.
- Do not use catch and throw unless you know exactly what you are doing (be careful with exception handling).
- Be clear about your intention. i=1-i is not the same as if(i==0) then i=1 else i=0.
- Fancy algorithms are buggier than simple ones, and they’re much harder to implement. (Pike)
- The first 90% of the code takes 10% of the time. The remaining 10% takes the other 90% of the time.
- All messages should be tagged.
- Do not use FOR loops as time delays.
- A user interface should not look like a computer program.
- Decompose complex problems into smaller tasks.
- Use the appropriate language for the job, when given a choice.
- Know the size of the standard data types.
- If you simultaneously hit two keys on the keyboard, the one that you do not want will appear on the screen.
- Patterns are for the weak—it assumes you don’t know what you are doing.
- Don’t assume precedence rules, especially when debugging—parenthesize.
- Do not use ++ and –. Use code like i = i + 1.
- It’s hard to see where a program spends most of its time.
- Fancy algorithms are slow when n is small, and n is usually small. (Pike)
- Assume that things will go wrong.
- Computers don’t know any math.
- Expect the impossible.
- Test everything. Test often.
- Do the simple bits first.
- Don’t fix what is not broken.
- If it is not broken, then try to break it.
- Don’t draw conclusions based on names.
- A carelessly planned project takes three times longer to complete than expected; a carefully planned project takes only twice as long.
- Any system that depends on human reliability is unreliable.
- The effort required to correct course increases geometrically with time.
- Complex problems have simple, easy to understand, and wrong answers.
- An expert is that person most surprised by the latest evidence to the contrary.
- One man’s error is another man’s data.
- 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.