Salesforce makes this process very difficult, and despite advice given by great guys on here I have become incredibly frustrated trying to make this work.
I am trying to change a custom objects API name (from Account_health__c to Asset_Health__c) that was very poorly chosen by a predecessor.
1st attempt: Simply change the API name in the object settings
Hahahah of course that won't work, Salesforce wouldn't do something useful like auto-update references for you, or wait for deploying from the sandbox before checking reference integrity. THAT WOULD BE TOO REASONABLE.
2nd attempt: Comment out apex references first in order to change the object API name
Nope, multiple editors/IDEs seem to stall on the saving process for any of these 'comment out' changes, including Aside.io, mavensmate and Salesforce's dev console. There seems to be some issue with commenting all but the top level class declaration of a class. Instead of saving the changes or throwing a save error, they stall indefinitely on 'Saving' then eventually throw metadata container errors when you try to cancel/resave. Great stuff.
3rd attempt: Pull all related class and object metadata, edit and deploy as package so they all update at once.
Here's the thing – How do I actually change the existing object's API name via metadata without creating a NEW object?
It's so frustrating! There is no 'label' or 'api Name' keys in the xml for the object. The API name of the object is determined by the name of the metadata file itself. But if I change the object's filename, it won't update the existing object, it will just create a new one!
Please help guys, its comical how frustratingly difficult they've made this process.
Best Answer
I think developers just become resigned to how painful simple refactoring like changing a name is after a while, either accepting the pain involved or choosing to just leave the bad name. Or choosing to move to a different platform.
(A Java project in an IDE naturally gets broken as you refactor and being able to work through the various changes and then eliminate errors is a natural way to work. Yes consistency checking is good but not when it blocks intermediate work steps.)
My general strategy could be summarised as:
This works for SObjects, SObject fields, and Apex. With a local copy of everything grabbed by an IDE, a copy of an SObject with a different name but the same fields can be made. And at least global search and replace can be used to do the change part consistently.
This approach avoids nasty situations in Apex where there are circular references. I've seen colleagues struggle for hours with compilation errors (often not clearly reported by the platform when the circular reference is indirect) when e.g. changing a constructor or method name. The add/change/delete approach keeps the code compiling (and therefore deploying) through each step.