I wanted to know if the way I deal with source files that need to be deleted from version control could be regarded as bad practice.
I want to explain it to you based on that example:
I recently got very angry because I had to tediously sort out Java classes in a programme that were basically dead code however it was nowhere documented and also not commented in those Java classes. Of course they needed to be deleted but before I delete such redundant stuff I have a – some may say strange – habit:
I do not delete such redundant files immediately via SVN->Delete (replace with delete command of your version control system of choice) but instead put comments in those files (I refer both at the head and at the footer) that they are going to be deleted + my name + the date and also – more importantly – WHY THEY ARE DELETED (in my case, because they were dead, confusing code). Then I save and commit them to version control. Next time when I have to commit/check in something in the project to version control, I press SVN->Delete and then they are eventually deleted in Version Control – still of course restorable through revisions though and this is why I adopted that habit.
Why doing this instead of deleting them right away?
My reason is, that I want to have explicit markers at least in the last revision in which those redundant files existed, why they deserved to be deleted. If I delete them right away, they are deleted but is nowhere documented why they were deleted. I want to avoid a typical scenario like this:
"Hmm… why were those files deleted? I did work fine before." (Presses
'revert' -> guy who reverted then is gone forever or not available in the next
weeks and the next assignee has to find out tediously like me what
those files are about)
But don't you note why those files were deleted in the commit messages?
Of course I do but a commit message is sometimes not read by colleagues. It is not a typical situation that when you try to understand the (in my case dead) code that you first check the Version control log with all the associated commit messages. Instead of crawling through the log, a colleague can see right away that this file is useless. It saves her/his time and she/he knows that this file was probably was restored for bad (or at least it raises a question.
Best Answer
The problem with adding a comment to a file that it should be deleted, instead of deleting it in source control and putting the explanation there, is the assumption that if developers do not read commit messages that they will surely read comments in source code.
From an outsider's perspective, this methodology seems to be rooted in a very conservative view of source control.
"What if I delete this unused file and then somebody needs it?" someone might ask.
You are using source control. Revert the change, or better yet talk to the person who deleted the file (communicate).
"What if I delete the dead file, then somebody starts using it again and they make changes?" someone else might ask.
Again, you are using source control. You'll get a merge conflict that a person must resolve. The answer here, as with the last question, is to communicate with your teammates.
If you really doubt a file should be removed, communicate before deleting it from source control. Maybe it only recently stopped being used, but an upcoming feature might require it. You don't know that, but one of the other developers might.
If it should be removed, remove it. Cut the fat out of the code base.
If you made an "oopsie" and you actually need the file, remember that you are using source control so you can recover the file.
Vincent Savard, in a comment on the question, said:
This is sound advice. Code reviews should be catching this kind of thing. Developers need to be consulting commit messages when an unexpected change is made to a file, or a file is removed or renamed.
If the commit messages don't tell the story, then developers also need to be writing better commit messages.
Being afraid to delete code or delete files is indicative of a deeper, systemic problem with the process:
These are the problems to address, so you don't feel like you are throwing rocks in a glass house when you delete code or files.