4 ms·
The advice from this post is exactly what you'd expect in theory and exactly what not to do in practice. For one simple reason: the source code is (hopefully)
by edw519 16y ago
The advice from this post is exactly what you'd expect in theory and exactly what not to do in practice. For one simple reason: the source code is (hopefully) the only thing pretty much guaranteed to survive.
I have seen countless shops where valuable history was lost because it was stored on someone's c: drive, a network drive, or some repository that failed to survive some kind of migration. And even if these other files (digital or paper) did survive, chances are that the programmer that needed to see them never did anyway.
Good shops practice keeping audit trails in the source code. This means good commenting. Which means good code review and quality control.
I recently came across a single piece of code that had been changed back and forth 6 times in the previous 2 years. The comments looked something like:
* jeo 02/11/09 Use Ship Date, not Book Date per Sarah in Sales
* jrm 04/15/09 Use Book Date to make military contracts balance
* msl 08/24/09 Use Ship Date per Joe in Ops (military no longer active)
* jrm 12/13/09 Use Book Date per Rick Smith to prepare for new contracts
* jrm 02/14/10 Use Ship Date per Rick Smith after Ops meeting
* jrm 05/25/10 Use Book Date per Rick Smith until Q3 migration
I know that this is an extreme example, but this stuff happens all the time in commercial environments. How easy do you think it would be for the programmer/analyst to provide background if these comments were not in the source code, but somewhere else?
Sure it's a pain it the ass to maintain this, but it immediately provides the needed background to the person who needs it, when he needs, where he's already working. For critical projects with confused users (what isn't), the alternative is usually much more work.
- pvg 16y agoHard to tell without context but these read very much version control commit messages, an audit trail nicely maintained by a VCS, along with the code it refers to. I think the main reason you see those sort of 'history of the world' comments is force of habit and the more cumbersome operation of older VC systems.
- Poiesis 16y agoUnfortunately, companies do occasionally change version control systems. History also tends to get lost when the codebase of one project is imported as the beginning of another.
- ondrasej 16y agoHowever, the current version control systems usually have compatibility layers and/or import tools. We have a project that started wih CVS, then moved to SVN and now runs on Hg, and we have the complete commit log (including commits from the CVS and SVN days) in the current repository.
- pvg 16y agoI don't think 'history tends to get lost'. It happens, both intentionally and unintentionally but preservation of history is a big, often deciding factor in such a switch. These types of comments are common, I think, not so much because it's so hard to migrate history but because the VCS in use doesn't have facilities for cheap local commit and there's no immediate local history. The workaround is to place important version-change information straight in the source. Which is perfectly sensible in those circumstances, I just disagree with the OP's idea that this is somehow a desirable or best practice.
- brown9-2 16y agoIf you treat the source code history as an essential artifact of the development process, and a piece of the product's history (which it is), then it is complete foolishness to switch systems without bringing the history over.
- brown9-2 16y agoGood shops practice keeping audit trails in the source code. No, "good shops" keep this level of detail in the source control system, something it was designed for.
- nitrogen 16y agoTo address the potential complaint that source control logs aren't as immediately accessible as source code comments, most editors and IDEs can hook into cvs/svn/git/Perforce, and most source control systems can insert the log into the source directly.
- suraj 16y agoIf you are putting audit trail in source code, merging changes from one release to another becomes a chore. Since there are no trivial merges anymore. You get conflicts in comments which have to be merged by hand. Also without ability to diff files, you are never sure what actually changed for a given comment. So you are dependent on VCS anyway! I have been burned by this in two large codebases (> 2k files).
- deleted 16y ago[deleted]
- ern 16y agoI'm currently maintaining a large project, and I find these sorts of comments frustrating, because "jeo", "jrm" and "msl" resigned years ago, and their initials are meaningless, since nobody remembers who they are. The names of the users who requested changes should be in version control commit messages, or better yet, in the bug tracker. Using programmers to deal with change requests from Sales, Ops and "Rick Smith" also seems very inefficient - you need some sort of analyst role to control changes and reduce this sort of thrashing.
- ajuc 16y agoComments are often obsolete, have to be maintained to be in sync with code. Comments can lie who is author of given change (somebody forgot to add comment after making change), while VCS can't. If you are afraid you VCS can be lost, the solution is to have better backups, not to reimplement VCS in comments.
- dennisgorelik 16y agoI too find "life story" comments useful.