Month: August 2014

Technical User Standards Design Experience Interface Documentation

If I had ever thought I would be doing a post on documentation, I would have made sure to have more topic starters in the back log. Let me put this out in the open, I hate writing documentation. Now that that is out of the way I feel empowered and what better way to express that than by judging all of you. I am going to guess that a great many of you hate documentation as well. Now don’t get put off by that statement or think I am belittling anyone in particular. I have seen it everywhere, on projects big and small, proprietary and open source, useful and utter garbage. Even my own git hub projects languish with bad documentation. Actually writing documentation, it seems, is farther down on my todo list than writing a blog post about writing documentation. Part of the problem is that once you start getting serious about documenting it appears that everyone has different ideas of the style, scope, and purpose. With every single sample different, finding a consistent thread of what a specific type of documentation is for, becomes an infuriating mess. If you are like me, this turns into mental gridlock as you agonize over how far you go with the details.

Let me paraphrase a joke I once heard: A group of developers were going over all the different formats their new media player would play. They narrowed it down to a list of 13 formats. Staring at the mess they thought to themselves, “Hey, we’re smart people, we should make a new format to overthrow and unify these other formats.” Then they had 14 formats to code to.

I mention that, because I will not be calling out one style of documentation above the rest. No, I will be adding my voice to the din. Just as a forewarning, I have no place telling anyone how documentation should be done. That being said, I will divide the documentation into three segments. The first will be the foundation, the second will be the stories, and the third will be the generated docs. They have been split based on their audience and their goal.

Foundation

I call this the foundation because it will have information pertinent to the entire project and is readable by everybody, from the managers to the developers. The goal here is to be only as technical as we need to be. To use a Heroku project as an example, this area will hold information like what technology is being used, what coding standards should be followed, what certification the app must meet, and any other project wide promises the app will be held to. Much of this paragraph is built off of section five in the book, Software Architecture for Developers. If your project is using MySQL instead of PostgreSQL, that goes here. If your project is being held to five 9s, god help you and that goes here. If  you have a specific task to submit your app for PCI certification, then that goes in the next section but the fact that it must be PCI certified goes here. So what is the next section?

Stories

I love stories. No, seriously, a well written user story is a wonderful thing to behold. I am basing this section off of my experiences with Jira, but I can think of no better place for documentation about what the project should be then right in the Jira stories themselves. These should contain all of the information about specific functionality that has been promised. The arrangement works out perfectly as all the information, including screen mocks can be added to the story. Questions and comments can be added as well to turn it into a living document, recorded for posterity. This should be a boon to QA testers who only have to look in one location to find out all the information on what a task should and should not do.

Code Documentation

While the above described what should happen, the code comments should communicate how. I am not talking about commenting every line of code, that is pointless and prone to error. Your code documentation should be twofold. First is structured comment blocks, ones that can be parsed by documentation generating tools, placed at the beginning of classes and at least on all public API. You can get the private methods to help out maintainers (and yourself) in the future. The next is inline comments, ONLY when there is a need to explicitly call out what you are doing. To use a real life example, to get JSTL referenced correctly in a recent project, I had to add in three lines of what can only be described as code voodoo. I added a comment stating not to remove it carelessly, why it was there, and a link to a page I got the piece of code from.

Conclusion

All told, with these three components there should be a complete picture with very little overlap or duplication. I say should because documentation is a soft skill. If you have bad code then you can get compilation errors, or test failures, or regressions in QA. Bad documentation can take a long while to surface, if they ever do. The side effect of bad documentation can be confusion, inefficiency, and delay that is hard to quantify but easy to feel. So whether it be a grain or a fast food serving worth salt, take this plan into consideration.

MavensMate Vs Force.com IDE

Are you looking for a no holds bared, pulse pounding, head-to-head match up between two established titans!? Then I am sorry, this is just a comparison between two code editors. I am sorry to have wasted your time. If, however, you came here looking for the type of fuel that can keep a flame war burning for way longer than it should have, then have I got a post for you. First let me frame this for anyone who isn’t in the know.

The force.com IDE was a plugin for Eclipse built on the metadata API. If you wanted to do any code editing out of the cloud, this was about your only choice. It was rough at times; tests were slow to the point of useless, there were a few missing features that people had come to expect from code editors, & it used the whole weight and heft of Eclipse to essentially act as a text editor with some fancy saving. MavensMate came along and, for some of my coworkers and myself, completely blew Force.com IDE out of the water. It was light, it was fast, there was code completion, there was an intuitive test results screen AND you could play games during a deploy. How cool is that! I suppose the only drawback is that the text editor it was a plug-in for, Sublime Text 3, is $80. That is not too bad considering how well loved Sublime is, but it is still something to keep in mind if you are going to be rolling this out to a large number of developers.

Ok, history lesson over. If you can’t tell by the fact that the above fight seems kinda lopsided and yet I am still writing, something has changed. The Force.com IDE has been released as open source and based off of the tooling API. Right off the bat this scores big with me since I am also a Java developer and can better understand what the code does. It is still an Eclipse plugin so that complaint still stands but lets see if it can wow us, shall we?

The Force.com IDE install process remains mostly unchanged and that is fine, as the Eclipse plugin manager is stable and robust enough to handle this easily. The project setup screen is also very familiar, though I did have to resize the ‘Choose initial project contents’ dialog  for the components to show up . It has a pile more choices for metadata types it can pull down, but it has always had that advantage. The tests were definitely faster, which was nice to see though the coverage report is lacking some polish. Two things I could not get working were the automatic builds and the code completion. The automatic builds caught me off guard as that was a feature that used to work. The code completion was something I was looking forward to working, but no dice. At this point I uninstalled and reinstalled, but it didn’t get any better.

When I set out to write this post, I wanted to be surprised. I will remember to be more careful with how I word my wishes. I was indeed surprised by how unimpressed I was. Compared to the old version, it did not feel like a significant improvement, or or an improvement warranting a blog post, or an  improvement at all. So I probably sound pretty down on the updated Force.com IDE, and I am, but I am hopeful. Releasing the source and making it much more possible to extend is a huge step forward. As it stands MavensMate still owns the Force.com IDE, but I will be happy to do another comparison in the future to see if the lead disappears.

Here comes NimbusMock!

Oh look, a git hub repo. That’s right, my mocking framework for apex has a name and a repo. Yay? Right now it is a 0.0.1 release. That means there is lots of chance for the api to change (I am still trying to decide whether to split out the object mocking and method stubbing). For now let’s see what it has to offer.

Class Setup in your Application

Before you can even hope to mock anything, there is a certian way to go about setting up your classes. The service classes must be setup with an interface. The point of the mock will be to override the default functionality with the mock methods. For any classes that are going to use these mocks, they must be setup so that the mocks can either be set in the constructor or a setter.

How to Mock

The first step, assuming your classes are all ready, is to make your mocks. In MockFactory.cls, create an inner class that extends NimbusMock and implements your interface. Your methods will simply call getCall with a unique name for that call in that class and an object array of your parameters. The following is a references for how to mock your calls:

 

Using your Mocks

Creating an instance of your mock is as easy as any regular class. For example:

From there, you need to tell the mock what to return or throw when a call is made with some combination of parameters. The base is the same in both cases, calling the when static method on NimbusMock and pass it the call to the mock method with the parameters you expect. After that you either chain thenReturn or thenThrow depending on what you want it to do. When put together, it looks something like this:

TODO

  • A generator for the mocks. I plan on writing this in apex and letting the devloper write up a script calling it with a list of classes they want mocked
  • The ability to set how many times the same call can be made and to see how many times a call is used after the fact
  • Mocking classes without interfaces. This isn’t that hard, I just need to settle on how I want to go about it