Documentation & Communication

I’ve Just Inherited an Application – Now What?

Posted in Developer Tools, Documentation & Communication, Java, UML & Diagramming on July 31st, 2012 by Christopher DeschenesBe the first to comment
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? read more »

 

Docs- Who needs them?

Posted in Developer Tools, Documentation & Communication on June 28th, 2012 by Christopher Deschenes1 Comment

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

read more »

 

Diagrams in Open Source & Successful Development

Posted in Documentation & Communication, Understanding Developers on September 7th, 2011 by Novita Mayasari1 Comment

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.

read more »

 

Diagrams- More than What Meets the Eye

Posted in Documentation & Communication, Understanding Developers on August 24th, 2011 by Novita MayasariBe the first to comment

“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.
read more »

 

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

Posted in Documentation & Communication, Understanding Developers, User Experience on July 27th, 2011 by Vineet Sinha10 Comments

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.
read more »

 

Herding Software Developers

Posted in Agile & Development Methodologies, Documentation & Communication on June 30th, 2011 by Seth Rosen1 Comment

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.
read more »

 

A Detailed Study on Understanding Code

Posted in Agile & Development Methodologies, Documentation & Communication, Java on March 19th, 2011 by Abhishek RakshitBe the first to comment

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.

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.

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).

read more »

 

New Years Resolutions of a Software Developer

Posted in Agile & Development Methodologies, Documentation & Communication on January 3rd, 2011 by Seth Rosen7 Comments

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.

read more »

 

Dealing with Complex Code: Where to Start?

Posted in Agile & Development Methodologies, Developer Tools, Documentation & Communication on November 11th, 2010 by Seth Rosen4 Comments

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 »

 

Understanding Code Visually: Three Ways that Work

Posted in Developer Tools, Documentation & Communication, UML & Diagramming on November 8th, 2010 by Seth Rosen19 Comments

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 »