Source code versioning with comments (organizational practice) - leave or remove? [closed] - version-control

Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 10 years ago.
Improve this question
Before you start admonishing me with "DON'T DO IT," "BAD PRACTICE!" and "Learn to use proper source code control", please hear me out first. I am fully aware that the practice of commenting out old code and leaving it there forever is very bad and I hate such practice myself.
But here's the situation I'm in. A few months ago I joined a company as software developer. I had worked in the company for few months as an intern, about a year before joining recently. Our company uses source code version control (CVS) but not properly.
Here's what happened both in my internship and my current permanent position. Each time I was assigned to work on a project (legacy, about 8-10 years old). Instead of creating a CVS account and letting me check out code and check in changes, a senior colleague exported the code from CVS, zipped it up and passed it to me.
While this colleague checks in all changes in bulk every few weeks, our usual practice is to do fine-grained versioning in the actual source code itself (each file increments in versions independent from the rest). Whenever a change is made to a file, old code is commented out, new code entered below it, and this whole section is marked with a version number. A note about the changes is placed at the top of the file in a section called Modification History. Finally the changed files are placed in a shared folder, ready and waiting for the bulk check-in.
/*
* Copyright notice blah blah
* Some details about file (project name, file name etc)
* Modification History:
* Date Version Modified By Description
* 2012-10-15 1.0 Joey Initial creation
* 2012-10-22 1.1 Chandler Replaced old code with new code
*/
code ....
//v1.1 start
//old code
new code
//v1.1 end
code ....
Now the problem is this. In the project I'm working on, I needed to copy some new source code files from another project (new in the sense that they didn't exist in destination project before). These files have a lot of historical commented out code and comment-based versioning including usually long or very long Modification History section.
Since the files are new to this project I decided to clean them up and remove unnecessary code including historical code, and start fresh at version 1.0. (I still have to continue the practice of comment-based versioning despite hating it. And don't ask why not start at version 0.1...) I have done similar something during my internship and no one said anything. My supervisor has seen the work a few times and didn't say I shouldn't do such clean-up (if at all it was noticed).
But a same-level colleague saw this and said it's not recommended as it may cause downtime in the future and increase maintenance costs. An example is when changes are made in another project on the original files and these changes need to be propagated to this project. With code files drastically different, it could cause confusion to another developer doing the propagation. It makes sense to me, and is a valid point. I couldn't find any reason to do my clean-up other than the inconvenience of a ridiculously messy code.
So, long story short: Given the practice in our company, should I not do such clean-up when copying new files from project to project? Is it better to make changes on the (copy of) original code with full history in comments? Or what justification can I give for doing the clean-up?
PS to mods: Hope you allow this question some time even if for any reason you determine it to be unfit in SO. I apologize in advance if anything is inappropriate including tags.

If copy of some file from another project really means (for this sources) "The point of divergence" and parallel independent evolution of source and fork, than legacy history and commented code are effectively "white noise" and can be easy eliminated on your side. For future possible propagation from parent mentioning of "bifurcation point" only will be sufficient in first line of Modification History, smth. like
...
* Date Version Modified By Description
* 2012-10-25 1.0 ADTC Created from 12.34 of <filename>
...
Addendum by asker (ADTC):
I wish to quote a comment in addition to the answer above.
[...] take the source code, remove the comments related to who did what (history comments), but retain the comment regarding what the source code/class/method does (informational comments). That is what the comment section is supposed to be. It should clearly define what the method is doing, how it is implemented and under what condition an exception will be thrown. – Wins, 2012-10-25 00:57:57Z

If I am I going your position, I'd prefer to modify the other source code and make it as library to be used within my project.

I suggest using some version control yourself - I recommend git. Have one branch for "upstream" code that is synchronized with whatever you senior colleague currently has. Then you can have one or more branches for your work. You will have good overview what changes you made using git diff against "upstream" branch, you can search history of everything you ever did on that project etc. And this all is automatic, without manual code versioning, the files are always "clean", with all their history available in git.

Related

Any thoughts on Surround scm? [closed]

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
So looking at different version control systems: subversion, accurev, surround, tfs, bitkeeper/git/mercurial
Subversion: I see it's quite the popular standard
Accurev: There seems to be a love hate relationship around it.
Surround and TFS: I haven't seen many comments around them.
Bitkeeper/Git/Mercurial: Seem pretty popular, but I think "distributed" may scare my manager lol
For some reason he seems attracted to Surround and it's not because of sales pitch. We had originally downloaded it for evaluation played around with it but nothing came of it. So now we are back to looking at scm and wants to try it again. So far I haven't seen any buzz around it like some other version control systems. Same for TFS
I've been using Surround SCM at my job and I'll say it is what it is, but there are a few things that I find lacking. Though, I've heard that surround scm integrates well with surround's issue tracking system, but I can't comment on that because we don't use that.
I personally find the UI to be buggy and confusing.
The workflows are confusing and often offer you with prompts that don't apply, so you get used to ignoring warnings.
eg. "are you sure you don't want to auto-merge?" "Are you sure you want to overwrite files?"
The UI always badgers you to use the auto-merge feature but every
time I've tried it, it ends up messing up my code (C#).
On top of that, the packaged diff tool (Guiffy) is buggy and doesn't display text
properly.
Weird workflow quirks can result in your changes being overwritten.
It doesn't do directory syncing
...which means that every time you add a new file to your project you must by-hand go and add it to the SCM repository. If you don't, everything will look normal to you until one of your teammates emails you because you broke the build.
There's no good way to copy over revision histories when you are branching
... which means that you are less likely to branch when you should be. There's nothing more frustrating than to have to store code locally because you're making changes right before a release and your team refuses to branch the code into another repository.
There's no good way to blacklist certain files from being checked-in or from being overwritten during an update.
If there's a file that you don't want to check-in then you're left with the painful chore of scanning through a long list of files and deselecting those you don't want every time you want to check-in. Yuck.
Features aren't documented that well
Of course, they release a user's guide but it's about as helpful as Microsoft Windows help function. It tells you step by step how to do things in the UI (ie. "click 'Create Shadow Directory', then click 'OK'", but it doesn't tell you what those features are, how they are intended to be used, what actually happens server-side etc.
Btw, if you know of any good way to get around these problems let me know :)
Danger! Danger, Will Robinson!
Surround is a data jail. Once you commit to it, you're stuck. There is no known way to get your history back out to another SCM. Don't get trapped!
This tends to be a problem with closed-source SCMs in general, but I have direct reports that it's especially bad with Surround.
Subversion, git, Mercurial, or Bazaar would be better choices.
I have used Surround at my job for about three years.
It does work well with their (Seapine's) test management and issue tracker program. If you are already using TestTrack, I would say Surround is a good choice.
In general I agree with #eremzeit, but the 'buggy and confusing' comment rarely applies to our workflow. The default diff tool (Guiffy) is bad, but often good enough.
One part I like is the easy ability to share files across repositories without needing to share a whole project/repository. Git does not have a mechanism to do this easily.
Last note: we have used Surround on Linux and Windows and it appears to work just as well on either. It is nice to have the same interface.
Surround SCM.
Pros:
Can apply a development work flow for all files. No two revisions of a file can be in the same status in the work flow.
Has a good UI.
Good licensing system.
Cons:
Stores all data in a RDBMS.. heading for a performance problem if the repo size is huge.
Does not support atomic commits. (you can do atomic commits but the files are still revisions and cannot be refereed using the changelist #)
My ideas about other tools
Subversion suits well for a corporate setup. Perforce is like subversion but faster and has a good UI, simple licensing terms and really super support system.
Recently Accurev has gained a strong footing with its innovative branching methodology.
IMHO. go for tool sets that interact well with your defect tracking, test case management and build management solution. This would help you create a good developer ecosystem thereby saving time.

File history: in the source or let scm handle it?

I'm learning mercurial as my solo scm software. With other management software, you can put change comments into the file header through tags. With hg you comment the change set, and that doesn't get into the source. I'm more used to central control like VSS.
Why should I put the file history into the header of the source file? Should I let mercurial manage the history with my changeset comments?
Let the source control system handle it.
If you put change details in the header it will soon become unwieldy and overwhelm the actual code.
Additionally if the scm has the concept of changelists (where many files are grouped into a single change) then you'll be able to write the comment so that it applies to the whole change and not just the edits in the one file (if that makes sense), giving you a clearer picture of why the edit was required.
Yes; let the source control system handle your changeset comments. The rationale for this is that it makes considerably more sense when you're viewing the change log later, trying to work out what's going on between two versions of a file - the source control system can present the change comment to try and enlighten the situation.
There's no reason to manually maintain a file history when SCM software is much better suited to solve this problem. All too often I see partially-completed file histories in the source, which actually hurts, because people incorrectly assume it is accurate.
The difference is not whether it's a centralized or distributed VCS, it's more about what's being changed.
When I moved to .Net, the number of files updated for any individual change seemed to skyrocket. If I had to log the change in each file, I'd never get any real work done. By commenting on the set of changes, it doesn't matter how many files I had to update.
If I ever needed to identify all of the changes for a particular change, I can diff between the two versions of the project.
The biggest difference (and advantage) I saw when switching away from SourceSafe was the switch from file based to project based commits. As soon as I got used to that, I stopped adding change-log type comments to all of my files.
(As a side effect, I've found that my process description comments have gotten better)
I'm not a big proponent of littering the code with change comments. In the event they are needed they can be looked up in the SCM (at least for the SCM variants I have used). If you do want them in the file, consider putting them at the end instead of the beginning. That way you won't have to scroll down past the (uninteresting, to me at least) comments before you get to the actual code.
Another vote for letting the SCM system handle the checkin comments, but I do have one thing to add.
Some systems allow you to use RCS tags in your source code where the SCM can insert the change history directly into the source file being committed automatically. Sounds like a nice balance because the history is then in the SCM system and then automatically put into the source code itself.
The problem is that this process changes the source file. I think that's a bad idea because the file cannot be changed on disk until after you comment is inserted. If you were a good engineer, you should have built and tested changes before the commit. If your source changes after the commit, then you've essentially got a build that could be broken - but most engineers won't build after a commit - why should they?
But it's just a comment you say! True, but I did have a case where there was code in my source file that strangely enough had reason to look like an RCS header tag and that section of the code got replaced on checkin, thereby munging my code. Easy enough to fix, but bad that a build got broken for 20+ users
Much easier to forget to maintain history in the source, as one always (imo) should comment commits to source control system that problem dissappers. Also if changing lots of files before commit, changing history in every file will be annoying work. This is really one of the points with having scm.
I have experience with this. I've had the file history in the comments, it was awful. Nothing but garbage, sometimes you would have to scroll down almost 1k lines of code changes before you finally got to what you wanted. Not to mention, you're slowing down other aspects of your build process by adding more kb to your source code tree.

When to start to use source control in early stages of development?

We have 2 kinds of people at my shop:
The ones that starts to check-in the code since the first successful compilation.
The others that only checks-in the code when the project is almost done.
I am part of group 1, and trying to convince people of group 2 to act like me. Their arguments are like the following:
I'm the solo developer of this project.
It's just a prototype, maybe I'll have to rewrite from scratch again.
I don't want to pollute the Source Control with incomplete versions.
If I am right, please help me to raise arguments to convince them. If you agree with them tell me why.
When someone asked for good excuses not to use version control, they got 75 answers and 45 upvotes.
And when they asked Why should my team adopt source control, they got 26 answers.
Maybe you'll find something helpful there.
You don't need "arguments to convince them." Discourse is not a game, and you should not use your work as a debating platform. That's what your spouse is for :) Seriously, though, you need to explain why you care how other devs work on solo projects in which other people are not involved. What are you missing because they don't use source control? Do you need to see their early ideas to understand their later code? If you can sucessfully do that, you may be able to convince them.
I personally use version control at all times, but only because I don't walk a tightrope without a net. Other people have more courage, less time to spend on infrastructure, etc. Note that in 2009, in my opinion, hard disks rarely fail and rewritten code is often better than the code that it replaces.
While I'm answering a question with a question, let me ask another one: does your code need to compile/work/not-break-the-build to be checked in? I like my branches to get good and broken, then fixed, working, debugged, etc. At the same time, I like other devs to use source control however they want. Branches were invented for just that reason: so that people who can't get along do not have to cohabitate.
Here's my view to your points.
1) Even solo developers need somewhere to keep their code when their PC fails. What happens if they accidentally delete a file without source control?
2/3) Prototypes belong in source control so other team members can look at the code. We put our prototype code in a seperate location to the mainline branch. We call it Spike. Here's a great article on why you should keep Spike code- http://odetocode.com/Blogs/scott/archive/2008/11/17/12344.aspx
If I'm the sole developer on a project (in other words, the repository, or part of it, is under my complete control), then I start committing source code as soon as it's written, and I tend to check in after every incremental change, whether or not it works or represents any kind of milestone.
If I'm working in a repository on a project with others, then I tend to try and make my commits such that they don't break the mainline development, pass any tests, etc.
Whether or not it's a prototype, it deserves to go into source control; prototypes represent a lot of work, and lessons learned from them are valuable. Plus, prototypes have an awful habit of becoming production code, which you'll want in source control.
I try to only write code that compiles (everything else is commented out with a TODO/FIXME tag)... and also add everything to source control.
Argument 1: Even as a single dev it's nice to roll back to a running version, to track your progress, etc.
Argument 2: Who cares if it's just a prototype? You might stumble upon a similar problem in six months or so, and then just start looking for this other code...
Argument 3: Why not use more than one repo? I like to file misc stuff to my personal repo.
Start using source control about 20 minutes before you write your first line of your first artifact. There is never a good time to start after you're begun writing things.
some people can only learn from experience.
like a hard drive failure. or coding yourself into a dead-end after deleting code that actually worked
now, i'm not saying that you should erase their hard drive and then taunt them with "if only you had used source control"...but if something like were to happen, hopefully there would be a backup done first ;-)
Early and Often. As the Pragmatic Programmers say, source control is like a time machine, and you never know when you'll want to go back.
I would say to them...
I'm the solo developer of this project.
And when you leave or hand it off we'll have 0 developers. All the more reason to use source control.
The code belongs to the company not you and the company would like some accountability. Checking in code doesn't require too much effort:
svn ci <files> -m " implement ajax support for grid control
Next time someone new wants to make some changes on the grid control or do something related, they will have a great starting point. All projects start off with one or two people. Source control is easier now than it ever was--have they arranged a 30 minute demo of Tortoise SVN with them?
It's just a prototype, maybe I'll have to rewrite from scratch again.
Are they concerned about storage? Storage is cheap. Are they concerned about time wasted on versioning? It takes less time then the cursory email checks. If they are re-writing bits then source control is even more important to be able to reference old bits.
I don't want to pollute the Source Control with incomplete versions.
That's actually a good concern. I used to think the same thing at one point and avoided checking in code until it was nice and clean which is not a bad thing in and of itself but many times I just wanted to goof around. At this point learning about branching helps. Though I wish wish SVN had full support for purging folders like Perforce.
Let see their arguments:
I'm the solo developer of this project.
It's just a prototype, maybe I'll have to rewrite from scratch again.
I don't want to pollute the Source Control with incomplete versions.
First, the 3rd one. I can see the reasoning, but it is based on a bad assumption.
At work, we use Perforce, a centralized VCS, and indeed we only check in source that compile successfully and doesn't break anything (in theory, of course!), after peer review.
So when I start a non trivial change, I feel the need to intermediary commits. For example, recently I started to make some changes (somehow, in solo for this particular task, so I address point 1) on a Java code using JDom (XML parsing). Then I was stuck and wanted to use Java 1.6's built in XML parsing. It was obviously time to keep a trace of the current work, in case my attempt was failed and wanted to go back. Note this case somehow addresses the point 2.
The solution I chose is simple: I use an alternative SCM! Although some centralized VCS like SVN are usable in local (on the developer's computer), I was seduced by distributed VCS and after briefly testing Mercurial (which is good), I found Bazaar better suited to my needs and taste.
DVCS are well suited for this task because they are lightweight, flexible, allow alternative branches, doesn't "pollute" the source directory (all data is in one directory at the root of the project), etc.
By making a parallel source management, you don't pollute the source of other developers, while keeping the possibility to go back or quickly try alternative solutions.
At the end, by committing the final version to the official SCM, the result is the same, but with added security at the level of the developer.
I'd like to add two things. With version control you can:
Revert to last version that worked, or at least check how it looked like. For that you would need SCM which supports changesets / uses whole-tree commits.
Use it to find bugs, by using so called 'diff debugging' by finding commit in history that introduced the bug. You would want SCM which support it in automated or semi-automated fashion.
Personally, I often start version control after the first sucessful compile.
I just wonder why nobody mentioned distributed version control systems in this context: If you could manage to switch over to a distributed system (git, bazaar, mercury), most arguments of your second group would become pointless since they can just start their repository locally and push it to the server when they want (and they can also just remove it, if they want to restart from scratch).
For me, it's about having a consistent process. If you are writing code, it should follow the same source control process that your production code does. That helps build and enforce good development practices across the development team.
Categorizing the code as a prototype or other non-production type of project should just be used to determine where in the source control tree you put it.
We use both CVS (for non .NET projects) and TFS (for .NET projects) where I work, and the TFS repository has a Developer Sandbox folder where developers can check in personal experimental projects (prototypes).
If and when a project starts to get used in production, the code is moved out of the Developer Sandbox folder into it's own folder in the main tree.
I would say you should start adding the source and checking in before you even build the first time. It is then much easier to avoid checking in generated artifacts. I always use some source control, even for my small hobby hacks, just because it automatically filters the relevant from the noise.
So when I start prototyping I might create a project and then before building it I do "git init, git add ., git commit -a -m ..." just so that when I want to move the interesting parts I just clone over using git and then I can add it to the subversion repository or whatever is used where I am working at the moment.
It's called branching people try to get with the program :p Prototyping? Work in a branch. Experimenting? Work in a branch. New feature? Work in a branch.
Merge your branches into the main trunk when it makes sense.
I guess people tend to be laid back when it comes to setting up source control initially if the code may never be used. I have projects I coded belonging to both groups and the ones outside source control are not less important. It is one of those things that gets postponed everyday when it really should not.
On the other hand I sometimes commit too seldom complicating a revert once I screw up some CSS code and not knowing what I changed e.g. to make the footer of the site end up behind the header.
I check-in the project in source control before I start coding.
The first thing I do is create and organize the projects and support files (such as .sln files in .NET development) with the necessary support libraries and tools (usually in a lib folder) I know I will use in my project.
If I already have some code written, then I add it too, even if it is an incomplete application. Then I check-in everything. From there, everything is as usual, write some code, compile it, test it, check-in it...
You probably won't need to branch from this point or revert your changes, but I think it is a good practice to have everything under source control since the beginning, even if you don't have anything to compile.
I create a directory in source control before I start writing code for a project. I do the first commit after creating the project skeleton.
i'm drunk and and i do first git -init and then vim foo.cpp.
Any decent modern source control platform (of which VSS is not one) should not in any way be polluted by putting source code files into it. I am of the opinion that anything that has a life expectancy of more than about 1/2 an hour should be in source control as early as possible. Solo develpment is no longer a valid excuse for not using source control. It is not about security it is about bugs and long term history.

Best Practices for Comments on Code Commit

What template do you use for comments on code commit?
One example of a template is:
(change 1): (source file 1.1, 1.2): (details of change made), (why)
(change 2): (source file 2.1): (details of change made), (why)
Ideally each change should be mapped to an issue in the issue tracker. Is this template alright?
Here are my thoughts... all these will be open to interpretation depending on your particular development methodologies.
You should be committing fairly often, with a single focus for every commit, so based on that, comments should be short and detail what the focus of the commit was.
I'm a fan of posting the what in your comment, with the why and the how being detailed elsewhere (ideally in your bug tracking). The why should be the ticket, and upon closing the ticket, you should have some kind of note about how that particular issue was addressed.
A reference to your bug tracking system is good if it isn't handled otherwise (TRAC/SVN interaction, for example). The reason for this is to point other developers in the right direction if they're looking for more information on the commit.
Don't include specific file names unless the fix really complex and detail is needed. Even still, complex details probably belong in bug tracking with your implementation notes, not in version control. Files edited, diff details, etc, should hopefully be included with version control, and we don't want to spend time duplicating this.
Given these ideas, an example commit comment for me would be something like
Req3845: Updated validation to use the new RegEx validation developed in Req3831.
Short, communicates what was changed, and provides some kind of reference for others to get more info without hunting you down.
I prefix each paragraph with + - * or !
+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix
I don't think you should commit detailed description about what parts of the code are changed, because that's why every VC has diff :)
If you use a bug tracking system, include relevant ticket numbers.
You do not need to mention changed files, or your name. The source repository can figure that out by itself. Describing the changes also only makes sense if it is not non-trivially obvious from the diff.
Make sure you have a good first line, because this frequently appears in the change history view, and people need to find things by this (the bug tracking ticket number should go there, for example).
Try to commit related changes in a single changeset (and split unrelated changes into two commits, even if to the same file).
I try to follow the same rule as for code comments:
Explain the WHY, not the HOW.
IMO a comment should contain a reference to the issue (task tracker, or requirement). Which files are affected is already available from the version control system. Apart from that, it should be as short as possible, but still readable.
I try to keep my fixes in separate check-ins.
I don't use an actual template, but a mental one, and it's like this.
Issue - dev level summary of
issue.
The issue tracker has all the management details, and the changes/diffs can be reviewed for code changes, so the comment is for dev's to understand the why/what of the issue.
Here's what I've seen used successfully:
Reference to bug number or feature ID
Brief description of the change. What was changed.
Code reviewer (to ensure you have one) unless handled by the checkin system.
Name of tester or description of which tests were run (if late in the process and you are being extra careful)
I use the simple technique described by Chaosben on the JEDI Windows API blog.
In order to get a fast view on the
changes made to a repository, we
suggest to write brief concise
comments starting each line with one
of these chars:
+ if you added a feature/function/…
- if you removed a feature/function/bug/…
# if you changed something
Doing it this way, other developers may find the desired revision much better.
First, commits should solve one single problem (separate commits for logically separate changes). If you don't know what to write in the commit message, or the comit message is too long it might mean that you have multiple independent changes in your commit, and you should split it into smaller items.
I think that commit message conventions expected and used by git makes much sense:
The first line of commit message should be a short description
If appropriate, prefix mentioned above summary line with subsystem prefix, e.g. "docs:" or "contrib:"
In next paragraph or paragraphs describe the change, explaining why's and how's
Keep in mind that if someone needs details of what changed, they can get a diff. That said, I just usually write a sentence or two for each major change, and then lump any minor fixes at the end.
There is no hard and fast rule as its plain english. I try to explain the work done in minimum words possible. Anybody looking for history of changes just want to know what happened in a particular change. If anybody is after more details then its there in the code.
Second thing I follow is if there is any bug associated then stick that in or if its related to any dev task then associate that with the change.
If two files were changed for different reasons, they should be in different commits The only time you should commit more than one code file at a time is because they all belong to the same fix/change

Best practices for version control comments

There is a lot of conversation about commenting code, but how about commenting on check-ins?
I found this blog post:
http://redbitbluebit.com/subversion-check-in-comment-great-practices/
As the guy who is putting together the release notes, I am looking for ways to make that job easier.
Currently we defined our own scheme with <Begin_Doc>...<End_Doc> for anything that should be published to our software customers. But even for the internal stuff, I'd like to know the "why" for every change.
Every feature has a ticket/issue/bugreport/task/whatever-you-call-it, and the ticket number is always referenced in the check-in comment. This gives context.
I would advocate NOT using/overloading your version control system for this. I would suggest the issue tracking software as a better fit.
For one, it does not seem appropriate to have developers add all the context and duplicated information in a commit message that is already in a requirements doc or issue/defect system.
You can use a tool to gather the relevant fixes/issue numbers that are in the commit comments and then go collect those from your other repository, but I think it is a mistake to basically make your revision tool an external facing thing.
You need to define what the Source/version repository/SVN is - is it for managing your source files, or is it also for writing release note. I think it should not be overloaded.
We try to keep it simple: write one sentence describing the change that you are committing. If a developer needs two or more sentences to describe the commit, then perhaps the commit is two unrelated pieces of work. When commits like this end up in version control, then it is difficult to revert fixes in isolation.
Another piece of information that we like to include in our commit comment is the defect / feature number that the commit fixes / implements. Not all work that we do is related to a defect in our issue tracking system, so this is not compulsory.
One last piece of information that we put in our commit comments is the name of one code reviewer. This is the person who did a sanity check on the changes before the commit takes place.
I recommend functional comments. The comments should give a summary of what was changed. If something was changed, and why. Every commit should be explainable, if you can't explain it clearly, you probably shouldn't be checking it in.
The most important thing to remember when using source control logs is they are there to determine when and what was changed. The more functional, and detailed the better. commits should be made in bite size pieces, that can be explained with bite size comments.
My personal preference is this style:
UPDATED the error logging system.
Added a legacy error parsing routine using regex to get the legacy error codes.
Changed the text in the database error messages, to correct misspellings.
Removed commented out sections of code, because they were not used any more.
The key is what are you going to do with the comments. If you're creating release notes, then you can do as you suggested. However I would recommend instead you keep track of release notes somewhere else, such as in a project management or bug tracking tool.
As for developer related comments, we've generally asked people to explain what they're doing, a one sentence explanation. It doesn't need to be too formal, mainly because if it is people will push back against it. Plus, if you know who did it, and you have a quick comment, you can generally trace back the issue and find the person.
As well, if you use a tool like FogBugz, you can link an SVN checkin to a case number. Which means that you can look up the case to get the full discussion, comments, screenshots, etc. Which is much more information than you could ever enter in a checkin comment.
Agree with Remembrance, but you should also write a little bit about why you implemented the change /bug fix the way you did.
If you belive in checking in often, you should also include TO DO's in order to make it possible for one of your co-workers to complete the task.
Making my changes small helps: I can provide detailed descriptions of my changes this way.
The checkin comments should be the information that a developer wants: this includes refactorings, motivation behind the code, etc.
On our projects we always advocate providing some detail to what a commit is about and to assist in not having to duplicate information like the problem we use Trac and have our repository integrated. The advantage is that you can then reference the issue ticket in the comment and only state the resolution or steps of work carried out. Trac then automatically links the reference number to the original issue number and applies your commit message as a comment to the issue. Then when you want to see what has been done you can simply read the issues within Trac and have full context.
With regards to release notes we have found that taking the list of issues within a release and using the commit information as a basis for the comments has worked fine. Generally you will not have release notes that have the raw commit messages in them as your clients do not really care about every little change or even the level of detail that may be included in the comment. So you would normally need to do a fair amount of editing to highlight the main changes and bug fixes implemented in that release.
I would say to try to follow a changelog style. The first line should be a short summary, and include the issue/ticket number (if any). This should possibly be followed by a blank line depending on how your VCS handles multi-line commit messages, then a fuller multiline description. I would say it's unreasonable to impose any strict formatting since it will discourage frequent commits, but so long as the important commits (the ones closing issues, or major changes) are done this way you should be ok.
If you use something like Trac or roundup + svn integration, it can pick out issue numbers from the commit messages. I would always put these in the first line since they're so useful.
Edit: Given that this is by far my most downvoted answer, I think it's worth emphasizing what's hidden in the last paragraph: I'm a sole proprietor. I have 100% ownership of these projects and do not work with other developers. In a shop with more than one developer, everything I'm saying in this answer may be completely inapposite.
I subscribe to DRY here as in all things.
I almost never add a comment to my commits. A comment is almost always repeating myself. The answer to the question "what changed in this commit"? is almost always in the diff.
When I'm looking at a file and I ask "what the hell happened here?", the first thing I do is look at the diff with the previous rev. 90% of the time the answer is immediately apparent, either because the code's self-evident or because there was something not self-evident that I commented in the code. If it's not, I correlate the rev dates of the file with the bug-tracking system and the answer is there.
This always works. It sometimes requires a little investigation to figure something out, because I didn't comment my code adequately. But I've never been unable to find the answer fairly quickly.
The only time I add a comment to the commit log is when I know that a diff isn't going to help me. For instance, when I sort a class's members: the only thing that a diff is going to tell me in that case is that something very big happened. When I do that, I commit the file as soon as I've fixed it. There's no appropriate place to comment a change of that scope in the file, so I add a comment to the effect that the only change in this rev is reordering the members.
("Why wouldn't you comment a change like that in the revision history at the top of the file?" you might ask. I don't keep a revision history at the top of my files. That was a scary, break-the-habit-of-a-lifetime change to make, and I've never regretted it for a moment. The revision history is Subversion.)
If I didn't have 100% ownership of the project, it might be different. It might be too hard to correlate commits with bug fixes. It might be too hard to train other developers to code to a style that makes it possible to rely on version control effectively. I'd have to see.