madebymany/sir-trevor-js — pull request #155 by cobbweb (2013-12-24 03:31:30+00:00)
Title: Refactor BlockStorage

Have done a bunch of changes to BlockStorage to hopefully make all the methods more understandable. This is taking off from [my comment](https://github.com/madebymany/sir-trevor-js/issues/94#issuecomment-30294640) about `toData()` in #94 but decided to do a little more while I was at it.

Every commit is pretty self-contained, incremental and tests were green with built version of sir-trevor (including minified). So it should be easy to remove some of these if we don't like them. Once were happy with this pull request I'll check over the final changes and see if tests should be added for anything.

Here's a summary of changes I made:

1. Changed `Block.toData()` to return the plain data object and *not* save it. I moved the saving part into `BlockStorage.save()`
2. Renamed `Block.toData()` to `Block._toData()` to indicate it's private. I think we should try and encapsulate the fact the the block storage and the UI aren't constantly in sync. Developers should use `getData()` instead of this.
3. Renamed `Block._toData()` to `Block._serializeData()`, I think this name describes what the method does better
4. Renamed `BlockStorage.getData()` to `BlockStorage._getData()` to indicate this is private. Again to hide the 'save' functionality, developers shouldn't use this method.
5. Renamed `BlockStorage.saveAndGetData()` to `BlockStorage.getBlockData()`. It still calls `save()`, but again trying to hide the `save` functionality.
6. Renamed `BlockStorage.saveAndReturnData()` to `BlockStorage.getData()`. Same as above, just trying to name this better. This should be the main method developers use to get data programatically.

Just to recap the rationale behind some of those commits in the middle. I think whenever a developer is trying to programmatically access block data, the UI and storage should always be in sync. Directly accessing the serialized data from the block or directly access the storage object should be discouraged unless you're hacking how the storage actually works.