Project Coding Guidelines

Topics: Project Discussion
Coordinator
Jan 5, 2013 at 1:08 AM

When contributing to Family Lines, we request you attempt to follow these general guidelines.

General Coding Guidelines

  • Follow existing code style. I.e. copy the existing code indentation,  brace styles, etc. 
  • Write explanatory comments for your code. Do not write "obvious" comments.   Write summary comments for any class, method or routine. Comments must be in English.
  • No embedded strings in code. Any string which might be visible to the user MUST be defined in resources. If you see an embedded string, move it to the resources. [This is for translation support. This restriction is temporarily waived for XAML.]
  • Avoid empty catch clauses. If there is a possible exception, catch it ASAP. A "TODO" comment is acceptable if you're not sure how to deal with an exception, but also write an email to the project coordinators.
  • Use 'try' methods rather than catch exceptions. E.g. use Date.TryParse().
  • When working on XAML, test your changes in both Black and Silver themes.  Any changes to the GUI should strive to maintain consistency with the existing "look". [Some .NET 4.0 controls may not be styled yet, if your changes are not styled automatically, write an email to the project coordinators.]
  • When working on XAML, avoid using fixed size or margin values. Ideally, controls should reposition/resize themselves as the window size changes.  [The existing codebase does not do this well, but will be modified over time.]

Testing Guidelines

  • Test your changes. Think of error scenarios and try them.
  • If possible, provide your tests to the team. E.g. if you created a GED or familyx file to exercise your changes, post it to [location to be  determined] along with an explanatory text file.

Data Guidelines

  • Maintain forward compatibility: insure the program still works if a .familyx file from Family.Show 4 is loaded. I.e. do not rely on loading only the "new" format.
  • Test save and load.
  • Always support GED import/export. If your data change can be imported from GED, do so. If an existing GED tag matches your data, use it during  export, after validating the tag is not already used. If you don't know,  advise the project coordinators. [We have not yet finalized our plans for custom GED tags.]