From 4f68eff8ca2ea61b04424b5dc9c7d0f3148dcce8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20=C3=96zkural?= Date: Wed, 26 Oct 2005 21:29:58 +0000 Subject: [PATCH] * express the concern about parenthetical expressions in more polite language * additional recommendations and a link to PEP 8 * would still need reorg... most of those aren't guidelines, just suggestions. --- CODING | 52 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 17 deletions(-) diff --git a/CODING b/CODING index 44e8f1e7..e03bb8f4 100644 --- a/CODING +++ b/CODING @@ -4,28 +4,46 @@ Oooooo. "Coding Standards". Guidelines ---------- +0. Before reading any further please observe + PEP 8: Style Guide for Python Code + http://www.python.org/peps/pep-0008.html 1. When using dirnames, don't expect the dir to end with a trailing slash, and please use the dirnames - in pisiconfig -2. Python indentation is usually 4 chars. + in pisiconfig. Use util.join_path instead of os.path.join +2. Python indentation is usually 4 spaces. 3. Follow python philosophy of 'batteries included' -4. Don't make the code have runtime dependencies on - a particular distribution (as much as possible) -5. Don't assume narrow use cases. -6. If you are changing something, check if that change +4. Use exceptions, don't return error codes +5. Don't make the PISI code have runtime dependencies on + a particular distribution (as much as possible). +6. Don't assume narrow use cases. Allow for a mediocre + amount of generalization in your code, for pieces that + will be required later. +7. If you are changing something, check if that change breaks anything and fix breakage. For instance a name. Running the tests is not always enough! -7. We all know, you're using LISP but didn't want to tell - us. Don't scare, as a success story and for your encouregment - there are tens of people on somewhere with LISP releated jobs. -8. If you are studying Data structures and Algorithms, and if - your first assignment is implementing a basic stack for - presedence, don't implement it. Just show your teacher the - syntax of LISP, tell him how beatifull it is, and show how can - otistic person can count lots of paranthesis with "one second" look, - probably you'll get A+. -9. If you are interesting with "Playstation 2 Linux Games Programming" - or "How to extend C programs with Guile", please don't. +8. A good design ensures separation of concerns. Every module + has a specific documented responsibility. Don't make the + horse clean your windows. +9. To ensure readability avoid nesting python constructs + more than 3 levels deep. Python is a good language (unlike C), + so you can define inner functions in a convenient way, use + such decomposition techniques to break down your code into + manageable chunks. The worst code you can write is one huge + procedure that goes on for 1000 (or more) lines. +10. Use a particular abstraction like a class or function only + if it makes sense. Don't just define things because they can + be defined. Define only things that will/may be used. +11. If you are doing an expensive task like searching through + 10000 text chunks, please use an efficient data structure + and algorithm. We are not MS engineers who know no data + structure beyond doubly linked lists and no algorithm beyond + quicksort. +12. Resist the temptation to develop kludges and workarounds in + response to pressure. Take your time to solve the problems by + the book. The payoff comes later. +13. Same thing goes for premature optimizations. Knuth and Dijkstra + are watching over your shoulder. :) + Unit testing ------------