As humans, we are constantly being bombarded with data throughout our lives. Thanks to the superb filtering and attention abilities of our brains we are able to make sense of all this information. Java programs and web apps need to rely on Lucene for this ability. Using Lucene, apps can now collect information at will, add it to an index, and retrieve whatever information is currently needed quickly and efficiently.

In my last post we learned the basics of creating and modifying a Lucene Index. Now I’ll give you some tips on how to query your index and avoid some of the pitfalls and stumbling blocks I’ve come across.
read more »

The hardest part in creating a user interface or complex feature is explaining to the user how it should be used. No matter how useful a feature is, if users can not figure out how to use it, it won’t provide them any benefit.

Tutorials and wizards can both help in getting users easily using features for the first time. Tutorials can be good at describing the steps necessary to perform a task where users may want to modify the steps in order to accommodate their specific needs. But tutorials do not typically live within your plugin/product and force users to switch between a tutorial on a website and your product. Wizards are great for taking a user through an ordered series of configuration actions but they also have their weaknesses. Wizards live entirely in a dialog box, which not only has to be designed by the development team, but also does not provide nearly enough flexibility. This is where a little known feature of Eclipse comes to the rescue.

read more »

One of my favorite parts of working at Architexa is that I get the chance to learn and experiment with new and interesting libraries, projects, and tools. One such project is Lucene. It provides a great infrastructure for indexing and searching any sort of text. This can be used for all sorts of applications and has saved us a great deal of time when keeping track of data in our projects.

read more »

When coding we often spend a significant amount of their time understanding new or unfamiliar code. Attempting to use a new library or fix a bug in a poorly organized component without first fully understanding the code we are working with can cause  headaches. Complex code can often be better understood through the use of diagramming tools (discussed here). However diagrams and other documentation cannot exist in a vacuum and there are tricks to better understand your code before attempting to diagram it. read more »

In trying to help developers understand code we have made sure to listen to what they have to say. We’ve noticed that many developers utilize UML style diagrams to try to understand code. However many problems exist with existing tools. I have tried using a number of UML tools and found that the reverse-engineering capabilities in the majority of them were not helpful for understanding tasks. They focus on designing tasks; reverse-engineering capabilities often just end up showing convoluted pictures and lots of useless information. Even developers that commonly use these tools ask us how to best understand code. Of course there are many solutions to this problem and the solution varies depending on the situation.

It is important to think about which specific perspectives you need to understand. Is the structure of the codebase in a state of disrepair and needs attention? Or are underlying code concepts, features, and logic the most important? There seem to be three main types of diagrams people use to help visually understand code.

read more »

Documenting code can be a time consuming challenge, especially when dealing with unfamiliar spaghetti code. Diagrams and UML tools can help with this but what appears to be a comprehensive diagram to one person might actually result in more confusion to someone else. It’s important to maintain a clear idea of what concepts your diagram is conveying. I often find myself attempting to document entirely with inline comments. This is often very useful but presents challenges when documenting concepts that span multiple classes/methods. There are several tricks I’ve found that make the task of diagramming code significantly easier.

read more »

One of the nice things about launching a tool is the opportunity it allows in talking to our users. Over the last 3+ months we have spent a great deal of time talking to development teams about Architexa, and have gotten a great deal of insight not only into what they like and don’t like about Architexa, but more importantly, what pains they have felt. The consensus is clear: while developers do need to focus on coding on a day-to-day basis, to be successful on a long term they need to worry about the parts of the system that are shared between team members. These worries where what we focused on for the most recent release (v2) or Architexa.
read more »

Layered diagrams seem to have become an integral part of documenting code well, but many developers don’t realize that they aren’t technically included in the UML spec. The UML standard provides a different sort of high level concept: the Package Diagram. It is often not clear when one should be used over the other, but I will attempt to show the strengths and weaknesses of both.

A layered diagram is useful for organizing and understanding the structure of a large code base from the top most level down. Instead  of using cumbersome directory trees or code searches to determine the relationships between packages, you can easily see them all in one space. Someone unfamiliar with the code base can easily examine a layered diagram and in a short time will have a grasp of the dependencies inherent in the project without having to be bogged down with details on classes or methods. It is also possible to include architectural components in a layered diagram, including databases, cloud/web components, and UIs. This allows for a flexible diagram that can show a great deal of information concisely.A project with a complex but easily understandable layered diagram is a sign of a well organized codebase.

read more »

The percentage of responders that said that they have used this diagram type. Class, Sequence, and UseCase diagrams stand out as the most often used.

Just the other day I was sent a link to a recent survey conducted by Dwayne Anius and Brian Dobing on the topic “Programmer’s views on the usefulness of UML diagrams”; a topic I am acutely interested in. In the survey approximately 100 developers responded providing information on their development experience and use of different UML diagrams. (you can add to this number by participating here) With millions of developers worldwide and only 100 represented in this survey it is difficult to get a general picture of the usefulness of UML but it is apparent from a cursory glance at the stats that Class Diagrams are the most widely utilized. This fits with the general consensus that class and sequence diagrams are the most preferred UML diagrams.

read more »

Recently I was testing a form for uploading a diagram to a server. Entering a name and description was easy enough but choosing a group to add it to caused some frustration. I had forgotten to add a new group for my diagram! The only solution available to me was to cancel the dialog and open a different one to create the group; a frustrating procedure. Imagine how much time is wasted every day by minor frustrations like this.

Forcing a user to make decisions (uploading a diagram) before all the necessary information is available (created groups) is the problem of the Cognitive Dimension Premature Commitment. If you have ever taken an online survey you have probably encountered this problem. Many surveys consist of multiple pages; users are often unaware of the type and number of questions that will be asked. Showing the user the number of total pages and their corresponding headers will allow users to confidently add or modify content during the current phase without having to backtrack. Premature commitment causes problems with all types of actions performed by users; whether it is the creation, modification, or exploration of content. It should be avoided at all costs.
read more »