Discussion and Support

Skip to content

It is currently Mon Feb 19, 2018 11:12 pm 

Reply to topic  [ 1 post ] 

Previous topic | Next topic 

  Print view

Author Message
User avatar  Offline
Site Admin
Joined: Mon Jun 12, 2006 12:20 pm
Posts: 12111
Location: Tampa, FL
 Post subject: READ ME before submitting source code patches
PostPosted: Mon Nov 01, 2010 9:43 pm 
Okay, here are some guidelines. Each of these should be accomplished before generating patch sets. Comments added to this thread that are acceptable (mostly to me, but also to Craig ;)) will result in this OP being edited and updated.

Much of this list is originally from this thread but since Craig and I have gained admin access to the SourceForge project I feel obligated to start putting some of this into place.

For now patches should be posted to the Testers forum. Access to that forum is by request only; send a PM to jfrazierjr here on the board and he'll add you to the group. You may then visit that hidden forum and review information on how to post patches for submission.

  1. Thou shalt always highlight the content of any Java source code thee hath modified and select Source -> Format. Note: this requires that the user reset the line length in the Eclipse properties: Trevor wants the line length set to 200 characters. (But see the attached preferences import file as the formatting settings are implemented there.)
  2. Thou shalt always select Source -> Reorganize Imports.
  3. Thou shalt always submit code that includes Javadoc comments for public classes and methods. (T'would be nice to require full Javadoc for everything, but alas, that is unlikely.)
  4. Thou shalt always use the /* */ style of comments in front of classes and methods and may use single-line comments in front of member variables and small snippets of code, but See Rule #3!
  5. Thou shalt always use parameter names different from member field names so that disambiguation using this is not necessary. (Exception: code generated by Eclipse's Source menu items is exempt from this requirement as a productivity enhancement.)
  6. Thou shalt always clearly delineate private constructors with comments so that those who come after thee may retain thy sanity.
  7. Thou shalt never use hard-coded strings in code when a property from an external file can be used. (In MapTool's case, this means calling I18N.getText(propertyKey) and adding a definition for the propertyKey to i18n.properties. Also, all of the show*() methods in MapTool, such as showError() and showWarning(), take propertyKeys as well as strings -- only use propertyKeys!)
  8. Thou shalt always use static final String's when hard-coded strings are appropriate. Examples include resources that are embedded inside the MapTool JAR, such as unknown.png -- the question mark image. Other image names that may be considered part of the "theme", such as toolbar images, button images, and so forth, should be retrieved from an images property file; I propose images.properties since we already have sounds.properties. A string in the code should reference a pathname in the property file.
  9. Thou shalt report all exceptions that are true errors. InterruptedException while waiting for a timer can be ignored, for example. But all other errors should be handled by calling MapTool.showError(propertyKey) or similar and passing both a propertyKey and the Throwable object representing the exception. Note that the various "show" methods already provide logging to the .maptool/log.txt file, but separate logging should be performed in the class if possible, since the XML configuration is an all-or-nothing for net.rptools.maptool.client.MapTool.
  10. Thou shalt always use defined properties instead of hard-coded strings when possible. Such as File.separator instead of "/" and now AppActions.menuShortcut instead of "ctrl".

There are surely others that you (the contributors) may want added and that we (the dev team) determine to be acceptable. Please speak up. :)

Edit: I've attached an exported set of Eclipse Preferences as a ZIP file. Unpack the ZIP and use File > Import... to read them. These preferences only include Java appearance and style-related settings, plus Task tag definitions. (Keyboard shortcuts and other settings are left untouched.)

File comment: This file is also included in the MapTool project @ sourceforge under the [b]conf[/b] directory.
eclipse-preferences.zip [4.11 KiB]
Downloaded 153 times
Display posts from previous:  Sort by  
Reply to topic  [ 1 post ] 

You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:

Who is online

In total there is 1 user online :: 0 registered, 0 hidden and 1 guest (based on users active over the past 5 minutes)
Most users ever online was 243 on Sun Nov 04, 2012 6:14 am

Users browsing this forum: No registered users and 1 guest

Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group

Style based on Andreas08 by Andreas Viklund

Style by Elizabeth Shulman