Code Style - UA-ScriptEase/scriptease GitHub Wiki

Let it hereby be forthwith decreed that from henceforth onward, Code Style shall be regarded as a window into the soul of the programmer.

-- Abraham Lincoln, probably

Model-View-Controller

Model represents all of the elements we are handling that get saved and loaded, like ScriptIts, StoryComponents, DescribeIts, etc. Our model resides in the "model" package. Never, ever, put a model object directly in the GUI. There are classes for displaying data, and classes for storing data, but they must never be the same thing.

In ScriptEase 1 this happened all the time - one class responsible for storing the properties of an Atom and being the object that was displayed the tree view. Beyond the obvious problem of one class having two distinct responsibilities, it created enormous headaches whenever the view deviated from the model. Just don't do it. The GUI and Model packages are separate for a reason.

View

Our view is in the gui package. It contains the visual representations of the model. If the class displays or alters Swing, it most likely belongs in here.

Controller

The Controller classes in the controller package are an interface between the View and the Model. Our controllers include such classes as exception handlers, events, observers, and formatting. We also have a translator package that works like another Controller. Code generation and translator operations go in here.

Other

We also have a util package. This contains basic utilities like String operations or the BiHashMap that we use in lots of different places.

  • Before you copy and paste some code, determine if it should be its own method.

  • Instead of having many classes that extend one class, create a factory class. For example, PanelFactory.java instead of extending JPanel many times.

  • Thoroughly comment each Java file in JavaDoc format. Don't comment what it's doing (unless it's obscure), comment why it does it. At minimum, write javadocs for public methods and classes. Make sure you sign any class you make any significant contribution to with an @author tag, and remember to update documentation after edits.

  • Comment any unclear code.

  • Name your variables with full, descriptive names. This is Java, not C. String a means nothing, whereas String displayName does.

  • Declare all of your variables used in a method or class at the top of their respective scopes. If the variables are only assigned once, declare them as "final" so that you do not accidentally change their values.

  • Use the for-each loop instead of a for loop whenever possible. Instead of for(int i = 0; i < list.size(); i++) { String element = list.get(i)..}, you can just use for(String element : list) { .. }

  • Avoid switch statements wherever possible. They are like a house of cards, always ready to collapse at the most inopportune moment. It is all too easy to forget a break; somewhere. Instead, use if/else blocks. Even better, use a Visitor when appropriate. See ModelVisitor.java for examples, and then see ModelAdapter.java to see how you can make it even more code friendly.

  • Do not simply "get it to work." Building prototypes is fine, but we can't afford to go back years later and fix a system because it was hacked together and left that way. That's ScriptEase 2 is supposed to be doing already. It's in your own best interest to be able to have a solid product on your resume.

  • Follow standard user interface conventions (ex: CTRL-Z for undo). Most of the problems we come across have already been solved in some system somewhere.

  • GUI information and error messages should only display a general description of what the notice or problem is. Remember, the non-technical users will read those. The detailed information should be printed to the log.

  • In addition to that, do not make programmer language visible to the user. Muggles have no idea what if statements, variables, getters, or bindings are.

  • If for some reason you put together some sort of hack, or you think a piece of code could , ALWAYS ADD A TODO, FIXME, OR XXX TAG WITH SOME DESCRIPTION!!! Otherwise, you'll later encounter some annoying bug somewhere else caused by this and likely have forgotten where it's coming from. Or the next IIP will encounter said bug, and they definitely will not have any idea where it's coming from.

  • If you do put a TODO, try to make an issue for it and then write the ticket number in the TODO itself. Otherwise there is a high chance that your todo item will be forgotten.