Pisilinux3/pisi
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Change to project/trunk,tags,branches style

Browse Source
This commit is contained in:
Faik Uygur
2009-10-14 12:42:24 +00:00
commit 54e89f07b4
1121 changed files with 136747 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CODING
+150
View File
@@ -0,0 +1,150 @@
Like every serious project, there are guidelines.
"Coding Standards" for serious.
Guidelines
----------
0. Before reading any further please observe
PEP 8: Style Guide for Python Code
http://www.python.org/peps/pep-0008.html
In particular this means no lameCaps
1. When using dirnames, don't expect the dir to end
with a trailing slash, and please use the dirnames
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. 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!
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. :)
Branches and SVN
----------------
There are two branches of pisi, one is called pisi-devel and
new features that are large enough to cause instability go
into that branch. The trunk version is supposed to be stable at
all times. This means that you *must* run unit tests and other
test scripts after committing any change that cannot be tested
in isolation. Run the unit tests periodically to catch unseen
bugs. A release from the stable branch *must not* break any tests
whatsoever, so extensive use of the test suite must precede any
release.
Unit testing
------------
Unit tests are located in unittests directory. Running the tests is
trivial. But you must synchronize your code and data with the test
code, which can be a tedious work if you lose discipline.
Sample data files are located in the same directory with test modules.
For running the entire test suite, use the following command:
$ ./tests/run.py
The following command will run tests in specfiletests and archivetests
in unittests dir:
$ ./tests/run.py specfile archive
Do not depend on the output of unittests. Instead of producing an
output message/data in your tests, check the data internally. By
definition, unittest should just report succeeding and failing cases.
If you didn't, take a look at the links below for having an idea of
unit testing.
http://www.extremeprogramming.org/rules/unittests.html
http://www.extremeprogramming.org/rules/unittests2.html
Other tests
-----------
There are a couple of nice test scripts for testing the basic
capabilities of the command line interface such as building and
upgrading. Unlike unit tests, you have to take a look at the output
to understand that the scripts are doing well :)
Misc. Suggestions
-----------------
1. Demeter's Law
In OO programming, try to invoke Demeter's law.
One of the "rules" there is not directly accessing any
objects that are further than, 2/3 refs, away. So the
following code is OK.
destroy_system(a.system().name())
but the following isn't as robust
destroy_system(object_store.root().a.system.name())
As you can tell, this introduces too many implementation
dependencies. The rule of thumb is that, in these cases
this statement must have been elsewhere.... It may be a
good idea to not count the object scope in this case,
so in Python self.a means only one level of reference,
not two.
One quibble with this: it may be preferable not to insist
on this where it would be inefficient. So if everything
is neatly packed into one object contained in another
object, why replicate everything in the upper level? If
the semantics prevents dependency changes, then chains
of 3 or even 4 could be acceptable.
OTOH, in Python and C++, it's not always good to implement
accessor/modifier pairs for every property of an object.
It would be much simpler if you are not doing any special
processing on the property (e.g. if what the type system
does is sufficient).
The main rule of thumb in Demeter's Law is avoiding
putting more than, say, 10 methods in a class. That works
really well in practice, forcing refactoring every now
and then.
2. We all know, you're using LISP but didn't want to tell
us. Don't be scared, as a success story and for your encouragment
there are tens of people somewhere with LISP releated jobs.
3. If you are studying Data structures and Algorithms, and if
your first assignment is to implement a basic FIFO queue,
don't implement it. Just show your teacher the syntax of LISP,
tell him how beautiful it is, and show how an autistic person
can count lots of parenthesis with a "one second" look, you'll
probably get A+.
4. If you are interested in "Playstation 2 Linux Games Programming"
or "How to extend C programs with Guile", please don't exercise
your valuable skills in this project.