VirtueMart - 1.1 Developer's Guide

Code

31

If  in  doubt,  lay  down  a  tag.  Tags  are  useful  for  pinning  down  a  particular  version  of  the  code,
e.g.  one  that  is  being  run  in  service,  or  just  before  a  big  change  or  import.  They  are  also  used  to
identify  branches.  Tag  names  should  be  short  and  meaningful,  like  variable  names.  For  example,

virtuemart-20051222

, 

pre-new-virtuemart

, 

fanf-patches

,  corresponding  to  the

uses mentioned above. Tags should be commented in the modules file.

Most of the guidelines in this section are common sense, but it's worth while re-iterating them in the
context of SVN because it has implications that might not be immediately obvious.

Never, ever reformat code. This is a really bad thing to do because it makes diffs hard to understand
and  apply.  Upstream  authors  won't  accept  patches  against  reformatted  code.  Bugfixes  and  patches
against the upstream code won't apply. New versions of the upstream code can't be imported. Real
changes get hidden in the mass of reformatting.

No-one's favourite coding style is significantly better or worse than anyone else's so reformatting code
provides no advantage to oppose the disadvantages.

Use the same coding style as the code you are editing. This is a corollary to the previous subsection.
It is easier for people reading the code if it uses consistent layout rules throughout, so when you are
editing someone else's code the code you add should be in the same style.

Tabs  are  four  characters  wide.  This  is  also  a  corollary  to  the  previous  subsections.  Although
indentation sizes vary greatly, tabs are almost universally eight characters, so using a different setting
is  liable  to  cause  confusion  or  even  reformatting.  A  four  character  tab  might  suit  your  indentation
style, but the rest of the world will think your code is a mess.

Commit messages are not a substitute for comments, or vice versa. Comments should describe
data structures and why the code does what it does; commit messages should explain why code was
changed.

 strings in your code. This makes it easier for people to know which version

of a file they have and where it came from, so that they can usefully refer to the file's SVN history
to find out about bugs and fixes, etc.

If your repository is configured appropriately, use the custom tag instead of 

$Header$

.

Because  of  limitations  in  SVN  certain  tasks  are  inherently  difficult,  particularly  recovering  from
mistakes. Although changing the repository directly is nearly always a Really Bad Idea sometimes it
cannot be avoided. These guidelines explain what to do in these situations.