Development Team/Code guidelines

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 localizators, 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 live 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 human 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 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.

Class design

When designing your classes and its 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.

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, though it is quite broad so it's not enough to guarantee a minimum of consistency.

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 docs. 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.