Do you add change history in source code? why?
-
I disagree entirely unless you're in a big shop. From everything I've ever seen on the subject it seems dangerous, fragile and adds an unnecessary level of complexity. Dangerous because it seems to foster a culture of not backing up properly and often. Fragile because they always seem to be breaking down or mangling code judging by the comments here and unnecessarily complex because well, it just is. For a very large shop with many programmers I can see the value, but let's face it, most of this stuff foisted on us is designed for factory code development, not for small versatile crafted code development.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
Couldn't agree more - I don't use an automated source code control at home (Visual SourceSafe etc) - only when onsite with larger clients.
------------------------------------------- Don't walk in front of me, I may not follow; Don't walk behind me, I may not lead; Just bugger off and leave me alone!!
-
We don't use VSS or any code repository and we *do* often keep a change history for anything that is complex or interesting. However if we did use a code repository (and I really see it as being more trouble than it could ever be worth in a small shop) I would still insist on the change history in comments because it would sure be a pain in the ass to not have that info right in front of you at all times. Comments cost nothing in the long run, as long as they are relevant they should always be front and center at all times.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
Man, I am caning you with 5's at the moment... Couldn't agree more with this one either!!
------------------------------------------- Don't walk in front of me, I may not follow; Don't walk behind me, I may not lead; Just bugger off and leave me alone!!
-
Our team add change history in source code all the time, and in my opinion it is NOT necessary. Because all source code are controlled by VSS. and we will write message while check in. So my question is, do you add change history in source code? what's reason add or not add? e.g
int i = j + m;changes to:// modified by XXX at ??? for bug#xxxx(begin) // int i = j + m; int i = j + m + 1; // modified by XXX at ??? for bug#xxxx(end)...Yes and no. We use TFS's attach work-item feature so that we don't have to manually enter this information everytime. But this approach is more time consuming than what we'd been doing for years. anyways, I've gotten in the habit of doing both and so far it has worked out well.
-
Thats horrible. We use a combination of subversion, trac and some open source wiki. If people use them correctly we can open a trac ticket and see a diff of the changes made to resolve it in the wiki. We also use the "blame" feature of subversion/tortise.
more details please thanks Martin
life is a bowl of cherries go on take a byte
-
I disagree entirely unless you're in a big shop. From everything I've ever seen on the subject it seems dangerous, fragile and adds an unnecessary level of complexity. Dangerous because it seems to foster a culture of not backing up properly and often. Fragile because they always seem to be breaking down or mangling code judging by the comments here and unnecessarily complex because well, it just is. For a very large shop with many programmers I can see the value, but let's face it, most of this stuff foisted on us is designed for factory code development, not for small versatile crafted code development.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
I strongly disagree. Source is the product, the most important thing we do. Once gone it is forever. Using a source control like tortoise/subversion is easy, and every programmer with more than 3 neurons (ok, it excludes VB users) should be able to use it.
There are two things that one must get used to or one will find life unendurable: the damages of time and injustices of men Fold with us! ¤ flickr
-
Our team add change history in source code all the time, and in my opinion it is NOT necessary. Because all source code are controlled by VSS. and we will write message while check in. So my question is, do you add change history in source code? what's reason add or not add? e.g
int i = j + m;changes to:// modified by XXX at ??? for bug#xxxx(begin) // int i = j + m; int i = j + m + 1; // modified by XXX at ??? for bug#xxxx(end)...No - never comment out code. The rule is no code should get into the application source without going through a human brain first. The two ways this can occur is : copy+paste or uncomment commented out code. Use a differential version control system if you want to know what the code used to be.
'--8<------------------------ Ex Datis: Duncan Jones Merrion Computing Ltd
-
Our team add change history in source code all the time, and in my opinion it is NOT necessary. Because all source code are controlled by VSS. and we will write message while check in. So my question is, do you add change history in source code? what's reason add or not add? e.g
int i = j + m;changes to:// modified by XXX at ??? for bug#xxxx(begin) // int i = j + m; int i = j + m + 1; // modified by XXX at ??? for bug#xxxx(end)...We tend to archive old obsolete projects (i.e. remove them from source control, and just leave the code tree read-only on a server somewhere) - every so often we might think "hey, this new bug sounds just like an old bug we fixed in xyz", when you haven't got checkin comments any more, it can be a major pain to find the bit of code that's relevant
-- Help me! I'm turning into a grapefruit! Buzzwords!
-
Yep, I initial and datestamp my changes in code almost all the time... After a while, (ie: once the changes have become obsolete due to further enhancements etc) I clear out the irrelevant comments while making said changes... Not only has this saved me a few times (someone broke this - is it initialed? No? Not me then!), but makes it easy to find all changes I have made by searching on my initials. Ultimately, pick a way you want to do it and do it consistently!
------------------------------------------- Don't walk in front of me, I may not follow; Don't walk behind me, I may not lead; Just bugger off and leave me alone!!
You hit the nail directly on the head! That's just what I do (except the datestamp only sometimes.) Five from me. BDF
-
I disagree entirely unless you're in a big shop. From everything I've ever seen on the subject it seems dangerous, fragile and adds an unnecessary level of complexity. Dangerous because it seems to foster a culture of not backing up properly and often. Fragile because they always seem to be breaking down or mangling code judging by the comments here and unnecessarily complex because well, it just is. For a very large shop with many programmers I can see the value, but let's face it, most of this stuff foisted on us is designed for factory code development, not for small versatile crafted code development.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
Even for single-programmers, source control is a must-have tool. At first I didn't use it, and when I started "using" it, it wasn't fully (a commit every week for example). But then I switched to Subversion/Tortoise and I started using it fully. Having every single version of the code and being able to diff between revisions is a great feature. Backups are easier, since you only have to backup the server and you get all revisions of all projects. Other features like automated builds and automatic unit testing are also better with source control, since the revision in the repository is the latest "official" release. And I won't talk about once you add another programmer to your "team"...
Luis Alonso Ramos Intelectix Chihuahua, Mexico
-
I strongly disagree. Source is the product, the most important thing we do. Once gone it is forever. Using a source control like tortoise/subversion is easy, and every programmer with more than 3 neurons (ok, it excludes VB users) should be able to use it.
There are two things that one must get used to or one will find life unendurable: the damages of time and injustices of men Fold with us! ¤ flickr
-
Disagree all you want but I see that you did not refute any of my statements about why I think it's dangerous fragile and unnecessary.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
-
I disagree entirely unless you're in a big shop. From everything I've ever seen on the subject it seems dangerous, fragile and adds an unnecessary level of complexity. Dangerous because it seems to foster a culture of not backing up properly and often. Fragile because they always seem to be breaking down or mangling code judging by the comments here and unnecessarily complex because well, it just is. For a very large shop with many programmers I can see the value, but let's face it, most of this stuff foisted on us is designed for factory code development, not for small versatile crafted code development.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
John Cardinal wrote:
I disagree entirely unless you're in a big shop
I think having a source control system is important for any size team, even a team of 1.
John Cardinal wrote:
Dangerous because it seems to foster a culture of not backing up properly and often.
If the source control system is maintained properly, the repository will be backed up nightly. Even in a small shop, the IT dept. (even if it's you as well) should have some sort of backup procedures in place. As far as not fostering a culture of backing up properly and often, it sounds like you are willing to place the burden of backing up on each individual developer by either requesting that they manually backup files or keep files in specific directory structures so IT can back them up. Both of these not only require manual intervention and potentially change developer habits but are also fraught with danger themselves. It does not easily accomodate hardware differences (for example, the developer who has been with the company a long time or works on a lot of different projects and has a 2nd hard drive that holds all of the project work) and doesn't take into account that people still turn off their machines at night (even if IT says not to) or takes them home.
John Cardinal wrote:
Fragile because they always seem to be breaking down or mangling code judging by the comments here
The fragility of the source control system is directly related to the system itself (some are simply better/more stable than others) and on how well it is maintained. It is also related to the size of the repository and, generally, a profound lack of understanding of how to properly setup the repository (or repositories).
John Cardinal wrote:
unnecessarily complex
How so? A lot of source control systems plug in to your IDE. Yes, it adds a few extra steps to either check-out or check-in (or both) the code, but I don't see that as "unnecassarily complex".
John Cardinal wrote:
For a very large shop with many programmers I can see the value
I think the values are there for any size shop. I personally used a source control system when I was in school as it saved me several times from stepping on my own feet. The benefits are that you can easily see who changed a part
-
We don't use VSS or any code repository and we *do* often keep a change history for anything that is complex or interesting. However if we did use a code repository (and I really see it as being more trouble than it could ever be worth in a small shop) I would still insist on the change history in comments because it would sure be a pain in the ass to not have that info right in front of you at all times. Comments cost nothing in the long run, as long as they are relevant they should always be front and center at all times.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
John Cardinal wrote:
Comments cost nothing in the long run, as long as they are relevant they should always be front and center at all times.
In general, this is true. The part that is bothersome is the "as long as they are relevant". I think a comment of the form
// Changed by xxx on 2007-09-20 (bug #xxxx)is completely irrelevant and doesn't put the information "front and center" as i still need to go to an external source to look up the details of the bug. If one were to put the full details of the bug in the comment, it would then be relevant and "front and center", except for the change history on the bug itself and it would potentially generate comment blocks so large that they actually start to obscure the code.Scott.
—In just two days, tomorrow will be yesterday. [Forum Guidelines] [Articles] [Blog]
-
John Cardinal wrote:
I disagree entirely unless you're in a big shop
I think having a source control system is important for any size team, even a team of 1.
John Cardinal wrote:
Dangerous because it seems to foster a culture of not backing up properly and often.
If the source control system is maintained properly, the repository will be backed up nightly. Even in a small shop, the IT dept. (even if it's you as well) should have some sort of backup procedures in place. As far as not fostering a culture of backing up properly and often, it sounds like you are willing to place the burden of backing up on each individual developer by either requesting that they manually backup files or keep files in specific directory structures so IT can back them up. Both of these not only require manual intervention and potentially change developer habits but are also fraught with danger themselves. It does not easily accomodate hardware differences (for example, the developer who has been with the company a long time or works on a lot of different projects and has a 2nd hard drive that holds all of the project work) and doesn't take into account that people still turn off their machines at night (even if IT says not to) or takes them home.
John Cardinal wrote:
Fragile because they always seem to be breaking down or mangling code judging by the comments here
The fragility of the source control system is directly related to the system itself (some are simply better/more stable than others) and on how well it is maintained. It is also related to the size of the repository and, generally, a profound lack of understanding of how to properly setup the repository (or repositories).
John Cardinal wrote:
unnecessarily complex
How so? A lot of source control systems plug in to your IDE. Yes, it adds a few extra steps to either check-out or check-in (or both) the code, but I don't see that as "unnecassarily complex".
John Cardinal wrote:
For a very large shop with many programmers I can see the value
I think the values are there for any size shop. I personally used a source control system when I was in school as it saved me several times from stepping on my own feet. The benefits are that you can easily see who changed a part
Ok, enough, enough, you've convinced me. You are the only person to do so because you brought up the only valid point that could possibly apply to our shop about branching the release version while working on the next version. Although we avoid custom and separate versions like the plague what you describe does happen and I will take a look and see what products are out there that would accomplish this and make sense for a very small shop. You do realize I was increasingly being tongue in cheek after the initial negative reaction I received for even daring to go against the doctrine of source control. :)
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
-
John Cardinal wrote:
Comments cost nothing in the long run, as long as they are relevant they should always be front and center at all times.
In general, this is true. The part that is bothersome is the "as long as they are relevant". I think a comment of the form
// Changed by xxx on 2007-09-20 (bug #xxxx)is completely irrelevant and doesn't put the information "front and center" as i still need to go to an external source to look up the details of the bug. If one were to put the full details of the bug in the comment, it would then be relevant and "front and center", except for the change history on the bug itself and it would potentially generate comment blocks so large that they actually start to obscure the code.Scott.
—In just two days, tomorrow will be yesterday. [Forum Guidelines] [Articles] [Blog]
99.9% of the time my comments in mature released code consist of //Case XXX where the case is the fogbugz case number. This is helpful in that in future I can see a specific change was made in an area and in case something breaks later on and I happen to be in that area looking at it. I don't need all the details as it takes 1 second to bring up the case in FogBugz and see what it was all about. The other sort of thing that I like to do is when I rewrite a method or a substantial or critical and complex area of code I like to keep the old code in place alongside the new code. Later on if I happen by that area of code and it's been a long time ago that it was changed (i.e. years) then I'll remove the commented code as general housekeeping.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
-
Ok, enough, enough, you've convinced me. You are the only person to do so because you brought up the only valid point that could possibly apply to our shop about branching the release version while working on the next version. Although we avoid custom and separate versions like the plague what you describe does happen and I will take a look and see what products are out there that would accomplish this and make sense for a very small shop. You do realize I was increasingly being tongue in cheek after the initial negative reaction I received for even daring to go against the doctrine of source control. :)
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
LOL. I guess the browbeating worked. :) Yes, I did realize that you were becoming increasingly more tongue-in-cheek with each response. I responded mainly because your chief complaint about all of the posts were that no one was actually responding to your arguements, which are all valid concerns. The biggest problem is that a lot of companies simply institute a source control system, where that system is just the repository software. They fail to understand the reasons behind what they are doing and that it actually requires a process in order to be effective. I think that is the root of the issue when you refer to it as being "foisted on the developers by management". The management knows they need something but fail to understand the process surrounding it (change control, etc.). There are a lot of source control products on the market and they all have pros and cons. I have used VSS in the past with relatively small projects (and know of people that have used it with great success on very large projects) but there are better things available. I have used CVS and Subversion (SVN) and much prefer SVN, but they really do require some time spent to understand how the repositories should be set up effectively. TFS is good, but expensive.
Scott.
—In just two days, tomorrow will be yesterday. [Forum Guidelines] [Articles] [Blog]
-
99.9% of the time my comments in mature released code consist of //Case XXX where the case is the fogbugz case number. This is helpful in that in future I can see a specific change was made in an area and in case something breaks later on and I happen to be in that area looking at it. I don't need all the details as it takes 1 second to bring up the case in FogBugz and see what it was all about. The other sort of thing that I like to do is when I rewrite a method or a substantial or critical and complex area of code I like to keep the old code in place alongside the new code. Later on if I happen by that area of code and it's been a long time ago that it was changed (i.e. years) then I'll remove the commented code as general housekeeping.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
This could also be handled by check-in comments, but it requires a bit more discipline from the developers. Ideally, a check-in comprises some sort of changeset (either formally, as is the case in TFS and Subversion, or informally). That changeset may comprise multiple files, but everything in the changeset should be related to one bug (or possibly multiple bugs if the bugs are related to each other). The check-in comment may reference the bug number (I say may because it ultimately depends on the systems being used; some of them do this automatically.) but should be descriptive enough to say what the changes were from a higher level (i.e., descriptions that say "Changed constant ABC to 1000" are meaningless; you see that from the diff history. What's important is WHY it was changed to 1000.) As for keeping the old version of the code in place alongside the new code, I also do that at times as well. The majority of the time I do that, however, is when I'm actively working on the rewrite...so there may be versions that get checked in with the commented out code. Ultimately it isn't necessary to keep the commented out code in the source file as you can see it in the version history maintained by the source control system. This, of course, is also a good reason for check-in comments to be meaningful. One company I worked at actually used the check-in comments to generate internal change log files as part of the build process. The internal change logs were then used by QA and Product Management to generate the information for the "real" change history that went in to the externally visibile readme files and website for each release. This practice very quickly taught the developers that the comments needed to be meaningful, but also not to write things they didn't want the company to see.
Scott.
—In just two days, tomorrow will be yesterday. [Forum Guidelines] [Articles] [Blog]
-
I disagree entirely unless you're in a big shop. From everything I've ever seen on the subject it seems dangerous, fragile and adds an unnecessary level of complexity. Dangerous because it seems to foster a culture of not backing up properly and often. Fragile because they always seem to be breaking down or mangling code judging by the comments here and unnecessarily complex because well, it just is. For a very large shop with many programmers I can see the value, but let's face it, most of this stuff foisted on us is designed for factory code development, not for small versatile crafted code development.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
John Cardinal wrote:
From everything I've ever seen on the subject it seems dangerous, fragile and adds an unnecessary level of complexity. Dangerous because it seems to foster a culture of not backing up properly and often. Fragile because they always seem to be breaking down or mangling code judging by the comments here and unnecessarily complex because well, it just is.
Backing up and source control are not the same thing. If you are not doing both then the lack of both of those, not one or the other, is dangerous and fragile.
John Cardinal wrote:
For a very large shop with many programmers I can see the value, but let's face it, most of this stuff foisted on us is designed for factory code development, not for small versatile crafted code development.
You should use source control because it is an automatic process that accurately maintains change history. Humans, as less than perfect both in practices and memory, are not as well equiped to do that. Attempting to maintain change history in the same code (such as commenting out old code) adds complexity to understanding code because there is more of it. Additionally it adds complexity issues because often changes are not simply a matter of addition or deletion but rather replacement. There are other peripheral benefits as well for instance in a legal proceedings about liability source control represents an exact record whereas other practices do not.
-
Our team add change history in source code all the time, and in my opinion it is NOT necessary. Because all source code are controlled by VSS. and we will write message while check in. So my question is, do you add change history in source code? what's reason add or not add? e.g
int i = j + m;changes to:// modified by XXX at ??? for bug#xxxx(begin) // int i = j + m; int i = j + m + 1; // modified by XXX at ??? for bug#xxxx(end)...WuJunyin wrote:
Our team add change history in source code all the time, and in my opinion it is NOT necessary. Because all source code are controlled by VSS. and we will write message while check in.
Far as I am concerned you are correct. Source control maintains an actual record of what did change. Comments record nothing more than what a particular developer wanted to comment on. Over time they clutter the code. If you are following stringent review processes and the comments that are being added to the code are reviewed as well then I wouldn't object as long as they were kept at the end of the source file (not the beginning.) If you are not doing reviews, doing them haphazardly, and not reviewing the actual comments then a developer in the future will not be able to use them anyways.
-
We don't use VSS or any code repository and we *do* often keep a change history for anything that is complex or interesting. However if we did use a code repository (and I really see it as being more trouble than it could ever be worth in a small shop) I would still insist on the change history in comments because it would sure be a pain in the ass to not have that info right in front of you at all times. Comments cost nothing in the long run, as long as they are relevant they should always be front and center at all times.
Never trust machinery more complicated than a knife and fork. - Jubal Harshaw in Stranger in a Strange Land
John Cardinal wrote:
However if we did use a code repository (and I really see it as being more trouble than it could ever be worth in a small shop) I would still insist on the change history in comments because it would sure be a pain in the ass to not have that info right in front of you at all times. Comments cost nothing in the long run, as long as they are relevant they should always be front and center at all times.
And of course as long as they are correct. And reflect what actually happened rather than what the developer thought happened. And if they are in there in the first place (I forgot, I didn't have time, I didn't know I needed it for that.) Of course without source control you have two choices to determine what actually did change. - Guess. - Rely on a back up and hope that the timespan is not to great (not to mention getting to the back up in the first place.)