| 5.4.2. Code |
| Prev | 5.4. Using SVN | Next |
|---|
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.
Include SVN $Header$ 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$.