Documentation & Communication

  • I’ve Just Inherited an Application – Now What?

    Lucene Overview Diagram

    What if I had a diagram like this?

    I have previously written about how lack of decent software documentation can cause problems in doing what we developers love to do, deliver functioning software. Documentation, code comments and good variable naming are all key to understanding code.  This applies to both code that we write and applications that we use through their API’s.  We could just as easily be looking at C/C++/C#, Python, PHP or any language but for now let’s stay with Java (read more about advantages of Java over other languages at theappsolutions.com .

    I want to illustrate how useful diagrams are in understanding an existing complex Java code base. Understanding code quickly is particularly important when inheriting a new project or trying to figure out how to use a third party package or open source project. As we all know we are typically faced with tight deadlines, limited resources, and herculean objectives. Sound familiar?

  • Docs- Who needs them?

    Software documentation is one of those things that is sorely missed when it isn’t there.  Why is it the last thing that any of us developers wants to do?  It seems that it is easy for us to ignore documenting in the heat of the situation, but we always get burned in one of many ways.

    Literate Programming Style Code View

  • Diagrams in Open Source & Successful Development

    When development teams are in the same room, it is not surprising to see diagrams being used – if only being shared via sketches made on pads, or through the use of whiteboards. Interestingly, despite the fact that OSS teams are distributed geographically, diagrams also play an important role in OSS development.

    There was a helpful research done by Koji Yatani et al. at University of Toronto and Oregon State University. They studied developers on the Ubuntu project and found that developers create and distribute digitalized diagrams as opposed to physical sketches. While the uses of diagrams are specific to the Ubuntu projects, there are definitely lessons that we can learn to apply in other OSS projects to ensure successful development.

  • Diagrams- More than What Meets the Eye

    “Diagrams?”

    Yes, diagrams. All of us use diagrams in one way or another. Mostly, diagrams are used to enhance communication and to illustrate what exactly one is talking about.

    “But that’s it. Diagrams are sketches which are meant to be thrown away without deserving a second look.”

    Now that’s where you’re wrong. In fact, diagrams are more useful than they appear to be. Yes, diagrams often become outdated fast in the software development industry and that tends to lead to people having a biased view against them. They often quickly assume diagrams are useless.

  • Making Code Easy to Understand – What Developers Want (a study)

    What exactly makes a codebase easy to understand; the documentation or the tools that you use? In our effort to help developers who are working with large codebases, we conducted a survey (see details and highlights) to find out what techniques developers use to better understand code.

  • Herding Software Developers

    Managing software developers can be a difficult task, especially when working with an agile team. Changing requirements and priorities combined with a learning and growing team can make even the most experienced managers sweat.

    Similar complex interactions have been studied in a number of fields. Game Theory, Cybernetics, and Chaos Theory all provide inspiration to managers looking to ease communication and improve the performance of a team. These theories along with many others fall into the category of Complex Systems. But as developers we need to be careful when utilizing concepts from other domains or managing developers may become an exercise in herding cats.

  • A Detailed Study on Understanding Code

    Let’s face it; code can be hard to understand. We have all encountered a piece of code that took longer than expected to figure out or was easy to misunderstand. It could be a new library, a coworker’s code, or your own code from 6 month’s ago.

    In a previous post we discuss the importance of taking time to study users in order to get feedback on innovative ideas. We did that to determine how developers understand code and why it can be a challenge.

    </p>

    We asked Open Source developers a number of questions. Two that stood out were their thoughts on the difficulty of understanding their code and what they generally wanted more of in such projects.

    </p>

    The first question we asked Open source developers was if they thought that the code they were working on was challenging to understand. Those using the libraries (API Clients) had a different take than those building the library (Core developers).
  • New Years Resolutions of a Software Developer

    Happy new year all! With the new year comes a chance to re-invent yourself, and as a software developer I find that it is a great opportunity to reflect on how I can improve my skills in the upcoming months. I have thought about this quite a bit over the last few days and have come up with a list of new years resolutions I intend to follow that will help me, and hopefully others, start the new year off on the right foot.

    Practice and experiment with new languages and frameworks for at least a day a month.

    Keeping up with the latest advancements in the software world can be challenging, especially when working at a fast paced start up. Nevertheless, taking time to investigate new and interesting languages and frameworks benefits not only your career, but may also provide streamlined solutions to problems at work. Having an array of languages and frameworks in your developer’s toolkit allows you to find the best solution to a wide range of problems. Career 2.0: Take Control of Your Life seems like it might be a good place to start investigating this resolution.

  • Dealing with Complex Code: Where to Start?

    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.

  • Understanding Code Visually: Three Ways that Work

    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.

  • Better Architectural Documentation in 5 easy steps

    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.

  • Implications of limited understanding in code..

    </p>


    We know that programmers do spend a lot of time understanding code. But what is not discussed as much are the implications of this limited understanding.

    The reality of implementing new features or just fixing bugs is that the architecture of our underlying system continues to change. With time pressures to deliver such code updates, code changes often need to be made without thorough understanding and as development continues the code quality deteriorates. As such development continues, the system grows into a state where the “Cost of Change” rises rapidly over time, and the inability to meet user needs leads to the failure of many projects.

  • Is your code poorly commented? Three indicators..

    One fact that is agreed upon – is that it takes a lot of time to understand code. Poorly commented code just makes this harder. The challenge that we face, is that developers’ often don’t want to take time away from coding to document, but working with code that is not commented takes more time in the long run.

    It is always nice to work on a project that has excellent commenting. However, there have been many projects that I have worked on that have frustrated me with the effort needed in understanding them. When code that I have been writing needs to build on badly documented components, I have sometimes added my own comments. Tragically, I have often not been responsible for maintaining such components and my effort in commenting has gone to waste – as I have not checked them in. Such code often has had three traits.

  • No, You are not Dumb! Programmers do spend a lot of time Understanding Code…

    While working on a codebase, developers spend a lot of time understanding code. We might be unwilling to admit it for fear of sounding dumb but the huge amount of time spent on making sense of code is staggering. In fact a conference is held every year just to tackle this problem...