CNX/Rhaptos Coding Standards
Document Actions
Submitted by
ew2.
on 2008-06-26 11:17.
CNX/Rhaptos Coding Standards
As we have more outside development on Rhaptos and Connexions, I think we need to have some minimum coding standards and guidelines. The main reason for coding standards is to make the code readable and maintainable by developers that come behind the original author. If we have coding standards, we all need to agree to them and follow them. They need to be policed at a certain level. Otherwise, what is the point? I would like to come up some simple standards we all agree on before the Siyavula development begins.
Coding Standards
We should adopt the python style guide as our coding standards with possibly some documented exceptions. Examples of exceptions:
- Limit lines to 79 characters. I don't agree with this. The only reason this would be needed is for printing. How often is code printed?
- Naming conventions
- Package and Module names should be all lower case with underscores between words. We are not following this.
- Function names should be all lower case with underscores between words. We are not always following this.
- Arguments to class methods should use 'cls' as the first arguement instead of 'self'. We are not doing this and I have not seen any code anywhere doing this.
- Use a leading underscore on the name of all non-public methods. We are not always doing this.
Comments
Comments in the code are not written for yourself, but for those that come after you. Comments should be in plain English with a limited amount of abreviations and jargon. I have heard the argument that if you can't understand the code by reading it, you are a (please select one or more) poor developer/stupid/too slow for this project/etc. I have found that the main benefit of good comments is helping bring new developers up-to-speed much faster. Comments on why you did something can also be very helpful when you revisit code you have not worked on in several months/years. A simple docstring guidelines could be:
- Each class, non-accessor method and function should
have a docstring that explains what it does and possibly why it is
doing it. It should also include a usage example if it is needed.
Re: CNX/Rhaptos Coding Standards
Posted by
jccooper
at
2008-06-26 12:27
See also: http://rhaptos.org/devblog/nmueller/csg-rhaptos
Re: CNX/Rhaptos Coding Standards
Posted by
reedstrm
at
2008-06-30 16:06
example of the class of 'override' skin template w/ comments about how and why it's overriding:
https://trac.rhaptos.org/trac/rhaptos/browser/RhaptosSite/trunk/skins/rhaptos_overrides/main_template.pt
https://trac.rhaptos.org/trac/rhaptos/browser/RhaptosSite/trunk/skins/rhaptos_overrides/main_template.pt
