Recent Changes - Search:



AlphaTcl style guidelines

Development.AlphaTclStyleGuidelines History

Hide minor edits - Show changes to markup

January 23, 2006, at 02:20 PM by -
Added lines 1-28:

(:title AlphaTcl style guidelines:)

This page is for listing and discussing the conventions which should be used for contributions to AlphaTcl.

First of all, if a package is entirely self-sufficient (e.g. a new mode), and you want to use your own formatting/tab/indent etc, you should feel free to do so. However, you may find others more reluctant to help out if your format is very different to the rest of AlphaTcl.

AlphaTcl uses a tabsize of 8 and an indentation amount of 4 in almost all files.

AlphaTcl code is free to use all the features of Tcl 8.4.

When contributing changes (or suggestions) to AlphaTcl, the following guidelines should be born in mind:

  • If you are making an obvious bug fix, just check the fix into cvs if you have developer permissions.
  • If you are a maintainer of a package, obviously you should feel free to do as you see fit
  • If you are not a maintainer of a package (or it is part of AlphaTclCore), and you wish to add a feature or make a less than obvious fix, then you should check with the maintainer of the package or the alphatcl-developer mailing list (or file a bug report or feature request on bugzilla).
  • It is rude to modify someone else's maintained code without asking first.
  • When submitting any patches/changes, try to focus the change on the issue at hand, and not mix in numerous cosmetic/reformatting/style changes. This will simply make it harder for someone to judge whether what you've done is helpful or not. Particularly if the package isn't maintained by you, the style changes might not be appreciated.
  • If you want to submit changes which are wholesale reformatting of files/packages (making them use more of Tcl 8's features, for example), please try to do so separate from any functional changes. That way the approval for such a change can be a simple decision. Remember that while namespaces allow one to write better code, they also allow one to write worse code!
  • The HEAD branch of the cvs repository is not for testing new ideas and new code. If you have an idea to test, announce it on the mailing list and solicit testers. Certainly if you have radical new ideas we can create a special cvs branch for them.
  • There seems to be a general acceptance amonst AlphaTcl developers of the idea that $::HOME is not a good idea, and global HOME ; ....; $HOME is clearer, and easier to maintain in the long term.
  • When making changes try to keep things simple -- try to reduce the number of connections between different pieces of code rather than increase them. We've put a lot of effort into detangling AlphaTcl over the last 5 years, but there's a lot more that needs to happen yet.
  • If in doubt, discuss an idea on AlphaTcl first, even without any code. This is especially true of large-scale changes to the way AlphaTcl works (e.g. we'd like to support user-defined bindings in all menus, but the design for this still needs to be worked out).
  • When adding new functions to AlphaTcl (particularly AlphaTclCore) keep them as minimal, clean and simple as possible. The same with user preferences: keep them to a minimum. Extra options for ways you think you might want to call the code at some future time should not be added. We can add options and preferences when there is a genuine need. Keep in mind the motto don't over-generalize, and don't generalize prematurely....

Any comments?


Page last modified on January 23, 2006, at 02:20 PM
Hosted on Logo