Coding Guidelines
To Live By

General Approach

1. Good general high-level design?
2. Considered other alternative approaches?
3. Working at the correct level of abstraction?
4. Using the right language/tool for the job?
5. Dogfooding – use it ourselves?
6. Reusable in the future?
7. Future-proof – designed for the world of the future?

New Files

1. Good filenames?
2. Following project's conventions?
3. Correct locations?
4. Correct permissions?

File Top Matter

1. Copyright & date(s)?
2. License?
3. Authorship?
4. Version history if not under version control?
5. Include/import order is project, libraries, system?

Code Formatting

1. Standard language indentation, spacing & bracketing?
2. No tabs, only spaces?
3. No lines longer than 80 characters?
4. Good spacing between function bodies?
5. Avoids functions longer than a page?
6. Uses vertical alignment to enhance readability?
7. Well spaced, clean & clear? Neatness counts!

General Code Quality

1. Good class names?
2. Good function/method names?
3. Good variable names?
4. Easily understandable?
5. As simple as possible? KISS!
6. Follows principle of least astonishment?
7. Extracts commonality & minimizes duplication?
8. No unnecessary public API? If in doubt, leave it out!
9. No unnecessary cuteness or cleverness?

Comments

1. Explains anything that is non-obvious?
2. Could come back & understand in 10 years time?
3. Unfinished parts marked with TODO?
4. Broken/incorrect parts marked with FIXME?

Memory Management

1. Clear object ownership?
2. No memory leaks?
3. Avoids memory never freed?

Error Handling

1. Validates incoming function args?
2. Uses assertions for assumption of valid args?
3. Considers corner cases, worst case scenarios?
4. Checks for all possible failures?
5. Catches all possible exceptions?
6. NULL-safe?
7. All paths through the code tested?
8. All error paths tested if possible?
9. Caller is appropriately notified of errors?

Security

1. Validates & sanitizes all user input?
2. No potential buffer overflows?
3. Creates files with correct ownership & permissions?
4. Secure, encrypted storage of passwords or private data?
5. Are the default settings secure?
6. Does it fail securely?
7. Minimized attack surface area?
8. Trust of other entities kept to a minimum?
9. Obeys principle of least privilege?
10. Separation of duties requiring different authority?
11. Obeys principle of defense in depth?
12. Not relying on security by obscurity?
13. If I was evil, how could I exploit this code?

Performance

1. Good algorithm & data structure choices?
2. Data structure member order optimized for size & use?
3. Args marked restrict if possible?
4. Common case fast?
5. Generally efficient?
6. Memory requirements minimized?
7. Scales to large inputs well?
8. No premature optimization?

Parallelism, Threading & Locking

1. Correct locking?
2. No missing locks, possible race conditions?
3. Locks acquired in strict hierarchy/order to avoid deadlock?
4. Avoids time sensitivity?
5. No possible priority inversion cases?
6. No blocking calls on main GUI thread?
7. No accidental calling of non-thread-safe API, directly or indirectly?

C Specific

1. Names lowercase with underscores between words?
2. Function args are ordered inputs, outputs, modifiers?
3. Const used where possible?
4. Avoids unsigned types unless necessary?
5. New header files have correct preprocessor guards?

C++ Specific

1. Names lowercase with underscores between words?
2. Ordering of declarations is private then public?
3. Private data members begin with an underscore?
4. Both copy constructor & assignment operator defined?
5. Copy constructor & assignment operator private if suitable?
6. Single arg constructors explicit if suitable?
7. Function args are ordered inputs, outputs, modifiers?
8. Const used where possible?
9. Objects passed by reference or const reference?
10. Variables declared at point of first use?
11. Avoids unsigned types unless necessary?
12. Exception-safe if library code?
13. No use of exceptions if application code?
14. New header files have correct preprocessor guards?
15. Correct namespace usage?

Objective-C Specific

1. Method & variable names use lower camelCase?
2. Class, type & function names use upper CamelCase?
3. No underscores in names?
4. Method names read like phrases?
5. Method names follow init-vs-autorelease convention?
6. Filenames include project prefix?
7. @private used in all class declarations?
8. Initializers funnel through designated initializer?
9. Designated initializer calls superclass' designated initializer?
10. Subclasses override all superclass initializers?
11. Class methods use self rather than fixed class name?
12. Uses ARC or reference counting, not GC?
13. Delegates & up pointers weak, or not retained if not ARC?
14. Nils out delegate pointers in dealloc if not ARC?
15. Nib outlets released if not ARC? (iOS only)
16. Dealloc handles partially initialized object?
17. Variables declared at point of first use?
18. Autorelease at point of initialization if not ARC?
19. No possibility of passing nil to collections or CF?
20. Checks return value not error arg for Apple APIs?
21. Avoids unsigned types unless necessary?
22. Uses isEqualToString not just isEqual?
23. Public properties are always set using setter method?
24. Special KVO methods needed for structs/collections?
25. Avoids categories with no name prefix?
26. Does not use Obj-C exceptions?
27. Obj-C exceptions enabled if @synchronized is used?
28. Includes description method for debugging?

Java Specific

1. Method & variable names use lower camelCase?
2. Class & interface names use upper CamelCase?
3. Package names use reverse domain name, all lowercase?
4. No underscores in names?
5. Methods grouped by functionality, not access?
6. All methods & instance variables specify private/public?
7. Provides proper documentation not just JavaDoc comments?
8. Doc comment lines, if used, no longer than 70 characters?
9. Variables declared at point of first use?
10. Uses close/cleanup methods, not relying on finalize() being called?
11. Also defines hashCode() if equals() is defined?
12. Tested on multiple different JVMs & OSs?

JavaScript Specific

1. Method, function & variable names use lower camelCase?
2. Constructor function ("class") names use upper CamelCase?
3. Uses a good JavaScript module pattern?
4. Global code enclosed in an anonymous function wrapper?
5. Only declares named inner functions at function scope?
6. Variables declared at function entry to match their hoisting?
7. No accidental use of block scope, unsupported in JavaScript?
8. No accidental use of implied global variables?
9. Constructor functions called with new?
10. Doesn't call methods using non-dot aliases?
11. Correct use of == vs === ?
12. Avoids using == to compare against null/false/undefined values?
13. Caches array length when iterating over arrays?
14. Avoids for in when iterating over arrays?
15. Uses hasOwnProperty() when iterating over all object properties?
16. Uses object & array literals rather than new Object()/Array()?
17. Always uses semicolons, never implied semicolon insertion?
18. Never modifies the prototypes of built-in objects?
19. Never uses the with statement?
20. Never uses typeof?
21. Never uses argument.callee?
22. Avoids using eval()?
23. Avoids implicit eval(), eg: strings in setTimeout()?
24. Never uses eval() on untrusted data?
25. Never uses document.write()?
26. DOM manipulation as efficient as possible?
27. Uses innerHTML rather than DOM functions where possible?
28. Uses querySelectorAll() or XPath for large DOM traversals, with fallback?
29. External script tags placed as late in the HTML body as possible?
30. External script tags set the defer or async attribute?
31. Tested on multiple different browsers, versions & OSs?
32. Extra-generous commenting in case a web designer has to maintain?

PHP Specific

1. Variable & function names lowercase with underscores between words?
2. Class names Title Case with underscores between words?
3. Private methods begin with an underscore?
4. Clean separation of presentation, logic & database access?
5. Combines SQL queries to avoid database queries inside loops?
6. SQL query keywords capitalized?
7. Correct use of == vs === ?
8. Uses single quoted strings where possible for performance?
9. All output properly escaped?
10. Uses full PHP tags (<?php ?>) not abbreviated tags (<? ?>).
11. No trailing spaces after closing PHP tags?
12. Extra-generous commenting in case a web designer has to maintain?

Perl Specific

1. Variable & function names lowercase with underscores between words?
2. Script names lowercase with nothing or dashes between words?
3. Uses strict & warnings modes? These cover most things.
4. Consider commenting regular expressions even if seems obvious now?
5. Uses modern #!/usr/bin/env perl shebang?

UNIX Shell Specific

1. Variable & function names lowercase with underscores between words?
2. Script names lowercase with nothing or dashes between words?
3. Variable expansion double quoted where necessary?
4. Single quotes used where necessary to avoid expansion?
5. PATH set to add necessary dirs?
6. Run under set -e to avoid continuing after errors?
7. Umask set to minimum necessary?
8. Temp files/dirs created securely using mktemp?
9. Trap set for unexpected error or kill?

Documentation

1. New docs needed?
2. Existing docs need changing?
3. Good, useful examples?

Anything More I Could Do?

1. Anything to be embarrassed about?
2. Less than best of the best?
3. What would another expert criticize?
4. What would a maintenance programmer not understand?
5. What if I died?
6. Any way to get user feedback soon?

Remember Priorities

1. 1. Practical correctness, reliability, always works?
2. 2. Formal correctness, elegance, standards compliance?
3. 3. Consistency, relentless consistency!
4. 4. Maintainability, flexibility, adaptability?
5. 5. Performance?