Apparently naming things is one of the hardest things in programming..!
I have a synchronisation implementation which uses timestamps (number of seconds since unix epoch) to sync.
Currently, the timestamps have simply replaced an older revision field. My question is, does it make sense to name it “Revision” or is “Timestamp” better?
Revision makes sense to me since that’s what’s used to version an entity – to know what’s created, updated, deleted. But if I needed to increase the granularity of the revision field in the future (ie. to become a decimal, to include fractions of a second), I wouldn’t be sure that a decimal revision would make sense. On the other hand, perhaps I want to move away from timestamps in the future (ie. to sequence numbers) in which case revision would make sense.
0
Just my opinion, but I would call it timestamp (or more precisely, modification timestamp), not revision.
-
It is a timestamp, so when it’s named
timestamp, someone seeing the field can infer when the file was last changed, whereas when it’s calledrevision, people might be confused to see a huge number, like1395653358, when it’s just the first or second revision of the file. -
If you want to change the format of the field, e.g. towards using decimal time (fractions of seconds) or a revision count, I would suggest using a different field for that, anyway. Imagine the confusion when the value of the
revisionfield is1395653358, and then for the next revision it’s3!
Having said that, the best option might be to create a dedicated class for this. This not only hides the internal representation (which can also be made up of several field, like date of creation and last change, revision count, comment, etc.), but can provide methods for comparing revisions or generating new revision numbers, whatever format is internally used.
1
If it’s simply a time stamp, and that is its only function, then call it a timestamp. If it has a larger purpose (i.e. Revision), then name it that.
Generally, it is better to name things by their function rather than their type. As you yourself pointed out, the type can change over time.
1
Revision implies that the field is updated when the object is changed. Revision does not necessarily imply that the field is a date/time, just that value is bumped each time the object is revised.
Timestamp implies that the field refers to the date/time that something happened. What? That’s not implicitly clear. Last change? Creation? Last time examined? The world can be used to refer to any of these conditions, so often another word is added to indicate what you’re tracking — “Creation Timestamp”, “Modification Timestamp”, etc.
2
Revision to me is a count of how many times the object has been edited, and possibly even with an audit history. A timestamp though is just that, a stamp of he last time changed, often used for concurrency checks. I’d obsolete the old property and create a new one for the timestamp.