Difference between revisions of "Development Team/Code guidelines"

From Sugar Labs
Jump to navigation Jump to search
m (some typos)
Line 1: Line 1:
<noinclude>{{ GoogleTrans-en | es =show | bg =show | zh-CN =show | zh-TW =show | hr =show | cs =show | da =show | nl =show | fi =show | fr =show | de =show | el =show | hi =show | it =show | ja =show | ko =show | no =show | pl =show | pt =show | ro =show | ru =show | sv =show }}</noinclude>{{TOCright}}
+
<noinclude>{{GoogleTrans-en}}</noinclude>{{TOCright}}
  
= Introduction =
+
== Introduction ==
  
The community around Sugar is very diverse and only a small part of it are directly involved in software development. Of those, an even smaller part is personally responsible for the quality of the software, its growth, and its availability to translators, distributors and deployers. See [[Development_Team/Release/Modules]] for a list of modules with their maintainers and peers.
+
The community around Sugar is very diverse and only a small part of it is directly involved in software development. Of those, an even smaller part is personally responsible for the quality of the software, its growth, and its availability to translators, distributors and deployers. See [[Development Team/Release/Modules]] for a list of modules with their maintainers and peers.
  
But this smaller group of people aren't the only ones that can contribute to the development of Sugar itself. Anyone with some spare time and enough skills and passion can make significant contributions to Sugar, but in order to bound to a limit the maintenance work the submitted code needs to have some characteristics, explained in this page.
+
But this smaller group of people aren't the only ones that can contribute to the development of Sugar itself. Anyone with some spare time and enough skills and passion can make significant contributions to Sugar, but in order to bound to a limit the maintenance work, the submitted code needs to have some characteristics, explained in this page.
  
Please take these recommendations with a grain of salt, they are intended to make the live of your fellow developers easier and are not intended to be general rules of "good programming".
+
Please take these recommendations with a grain of salt, they are intended to make the life of your fellow developers easier, and are not intended to be general rules of "good programming".
  
= It's all about communication =
+
== It's all about communication ==
  
 
Your code will run as interpreted by the Python interpreter, but other people won't be able to efficiently work with it if you don't address people as well when writing it. Write your code first for people and secondarily for the machine.
 
Your code will run as interpreted by the Python interpreter, but other people won't be able to efficiently work with it if you don't address people as well when writing it. Write your code first for people and secondarily for the machine.
  
= Consistency =
+
== Consistency ==
  
 
If you are going to do things differently, be sure to have a really good reason. Often a bad standard is better than no standard at all.
 
If you are going to do things differently, be sure to have a really good reason. Often a bad standard is better than no standard at all.
  
Just because it looks smarter is probably a bad reason, as most of the people that will be reading at your code won't be doing it by pleasure or edification but in order to fix bugs or add features. In those cases it's better when code is boring and predictable.
+
Just because it looks smarter is probably a bad reason, as most of the people that will be reading at your code won't be doing it for pleasure or edification, but in order to fix bugs or add features. In those cases, it's better when code is boring and predictable.
  
= Class design =
+
== Class design ==
  
When designing your classes and its dependencies, keep [http://en.wikipedia.org/wiki/Coupling_%28computer_science%29 coupling] low and [http://en.wikipedia.org/wiki/Cohesion_%28computer_science%29 cohesion] high.
+
When designing your classes and their dependencies, keep [[wikipedia:Coupling_%28computer_science%29 |coupling]] low and [[wikipedia:Cohesion_%28computer_science%29 |cohesion]] high.
  
Avoid reference cycles and use signals to break such cycles when redistributing responsibility is not enough.
+
Avoid reference cycles, and use signals to break such cycles when redistributing responsibility is not enough.
  
 
Keep the size of your modules, classes, methods and functions under reasonable limits. Splitting a method in two is a good opportunity to put a name to a block of code.
 
Keep the size of your modules, classes, methods and functions under reasonable limits. Splitting a method in two is a good opportunity to put a name to a block of code.
Line 29: Line 29:
 
Make sure that [[Development Team/API policy|API policy]] rules are respected.
 
Make sure that [[Development Team/API policy|API policy]] rules are respected.
  
= Code style =
+
== Code style ==
  
 
First rule is to use the same style as the existing code around your new method, class or module. Sugar code is quite consistent as of now (August 6th 2009) so you shouldn't need to change styles often except when modifying very old code.
 
First rule is to use the same style as the existing code around your new method, class or module. Sugar code is quite consistent as of now (August 6th 2009) so you shouldn't need to change styles often except when modifying very old code.
Line 39: Line 39:
 
Python is a very expressive language that allows for different programming models, before using the more exotic features consider readability over compactness and think that we want people to be able to contribute to Sugar without needing to be familiar with the whole Python syntax.
 
Python is a very expressive language that allows for different programming models, before using the more exotic features consider readability over compactness and think that we want people to be able to contribute to Sugar without needing to be familiar with the whole Python syntax.
  
= Tools =
+
== Tools ==
  
When possible use tools to check your code, this will save lots of time to everybody involved.
+
When possible use tools to check your code, this will save lots of time for everybody involved.
  
Please try to use [http://www.logilab.org/857 pylint] to verify your patch for things like exceeding 80 columns etc, unused imports and unused variables. Pylint is not a tool you can rely on 100% but it helps to follow some guidelines and to avoid the most stupid errors like typos. sugar-jhbuild contains a pylintrc you can use in the <code>scripts/data</code> directory: [http://git.sugarlabs.org/projects/sugar-jhbuild/repos/mainline/blobs/master/scripts/data/pylintrc pylintrc] (follow "raw blob data").
+
Please try to use [http://www.logilab.org/857 pylint] to verify your patch for things like exceeding 80 columns etc., unused imports and unused variables. Pylint is not a tool you can rely on 100% but it helps to follow some guidelines and to avoid the most stupid errors like typos. sugar-jhbuild contains a pylintrc you can use in the <code>scripts/data</code> directory: [http://git.sugarlabs.org/projects/sugar-jhbuild/repos/mainline/blobs/master/scripts/data/pylintrc pylintrc] (follow "raw blob data").
  
 
[http://svn.browsershots.org/trunk/devtools/pep8/pep8.py pep8.py] catches more style errors than pylint, so make sure to run that one, too.
 
[http://svn.browsershots.org/trunk/devtools/pep8/pep8.py pep8.py] catches more style errors than pylint, so make sure to run that one, too.
Line 49: Line 49:
 
In the sugar packages use 'make distcheck' to make sure all files are included and the POTFILES.in is up to date.
 
In the sugar packages use 'make distcheck' to make sure all files are included and the POTFILES.in is up to date.
  
= Buildbot =
+
== Buildbot ==
  
 
We are running periodic builds of Sugar using [http://buildbot.sugarlabs.org Buildbot]. If you break the build you are responsible to get it fixed. If you don't, the release team will take care of it, most likely by reverting your patch. More in detail:
 
We are running periodic builds of Sugar using [http://buildbot.sugarlabs.org Buildbot]. If you break the build you are responsible to get it fixed. If you don't, the release team will take care of it, most likely by reverting your patch. More in detail:
Line 58: Line 58:
 
You can use the check command in jhbuild to execute the same checks that [http://buildbot.sugarlabs.org/ Buildbot] is doing.
 
You can use the check command in jhbuild to execute the same checks that [http://buildbot.sugarlabs.org/ Buildbot] is doing.
  
= References =
+
== References ==
  
 
http://developer.gnome.org/doc/guides/programming-guidelines/index.html
 
http://developer.gnome.org/doc/guides/programming-guidelines/index.html
 
https://developer.mozilla.org/En/Mozilla_Coding_Style_Guide
 
https://developer.mozilla.org/En/Mozilla_Coding_Style_Guide

Revision as of 20:56, 22 August 2009

Introduction

The community around Sugar is very diverse and only a small part of it is directly involved in software development. Of those, an even smaller part is personally responsible for the quality of the software, its growth, and its availability to translators, distributors and deployers. See Development Team/Release/Modules for a list of modules with their maintainers and peers.

But this smaller group of people aren't the only ones that can contribute to the development of Sugar itself. Anyone with some spare time and enough skills and passion can make significant contributions to Sugar, but in order to bound to a limit the maintenance work, the submitted code needs to have some characteristics, explained in this page.

Please take these recommendations with a grain of salt, they are intended to make the life of your fellow developers easier, and are not intended to be general rules of "good programming".

It's all about communication

Your code will run as interpreted by the Python interpreter, but other people won't be able to efficiently work with it if you don't address people as well when writing it. Write your code first for people and secondarily for the machine.

Consistency

If you are going to do things differently, be sure to have a really good reason. Often a bad standard is better than no standard at all.

Just because it looks smarter is probably a bad reason, as most of the people that will be reading at your code won't be doing it for pleasure or edification, but in order to fix bugs or add features. In those cases, it's better when code is boring and predictable.

Class design

When designing your classes and their dependencies, keep coupling low and cohesion high.

Avoid reference cycles, and use signals to break such cycles when redistributing responsibility is not enough.

Keep the size of your modules, classes, methods and functions under reasonable limits. Splitting a method in two is a good opportunity to put a name to a block of code.

Make sure that API policy rules are respected.

Code style

First rule is to use the same style as the existing code around your new method, class or module. Sugar code is quite consistent as of now (August 6th 2009) so you shouldn't need to change styles often except when modifying very old code.

Follow PEP 08, but as it is quite broad, it's not enough in itself to guarantee a minimum of consistency. Some more comments below.

Use inline comments sparingly. If you feel your code needs an inline comment, consider instead splitting the method in two, with a reasonable name and API comment. API comments should say what the code does, not how it does it. How your code works should be clear from the code structure, refactor until the code structure is a clear reflection of its purpose.

Python is a very expressive language that allows for different programming models, before using the more exotic features consider readability over compactness and think that we want people to be able to contribute to Sugar without needing to be familiar with the whole Python syntax.

Tools

When possible use tools to check your code, this will save lots of time for everybody involved.

Please try to use pylint to verify your patch for things like exceeding 80 columns etc., unused imports and unused variables. Pylint is not a tool you can rely on 100% but it helps to follow some guidelines and to avoid the most stupid errors like typos. sugar-jhbuild contains a pylintrc you can use in the scripts/data directory: pylintrc (follow "raw blob data").

pep8.py catches more style errors than pylint, so make sure to run that one, too.

In the sugar packages use 'make distcheck' to make sure all files are included and the POTFILES.in is up to date.

Buildbot

We are running periodic builds of Sugar using Buildbot. If you break the build you are responsible to get it fixed. If you don't, the release team will take care of it, most likely by reverting your patch. More in detail:

  • Every change that causes build or check failures should be immediately fixed or reverted.
  • Every change that causes check warnings should be fixed or reverted within 24 hours.

You can use the check command in jhbuild to execute the same checks that Buildbot is doing.

References

http://developer.gnome.org/doc/guides/programming-guidelines/index.html https://developer.mozilla.org/En/Mozilla_Coding_Style_Guide