Software Reuse Quick Tip #11

Tip #11 Document Capabilities as well as limitations of reusable software assets

When documenting a reusable software asset donot only capture only capabilities. Be sure to document limitations as well. This is important because limitations directly influence refactoring work. When trying to match a user story with an existing asset the limitations will determine the extent to which you need to update the existing code in order to implement the story. Limitations are not a bad thing per se especially since you want to prioritize overcoming them within the context of a real user need. This exercise is made a lot easier when you capture the limitations ahead of time – this way you don’t have to review your code or ask several developers in order to come up with the refactorings needed.

Like this post? Subscribe to RSS feed or get blog updates via email.

add to Digg it : post to facebook: Stumble It! : :

2 Responses to Software Reuse Quick Tip #11

  1. Jing says:

    Where would you document these assets? Javadoc? Separate word doc? What have you found to be more effective and maintainable?

  2. I would recommend a lightweight tool – you can start with even a word document if you have a small set of reusable assets. What I use is a wiki – setup a page for each asset and keep updating it based on releases/iterations. Wiki is simple to use and if you are uncomfortable opening it up for anyone to edit you can have a designated owner for updating the contents and let reviewers provide feedback by adding comments on the wiki page. Javadocs are great for communicating the point-in-time state of the API but i haven’t found it convenient for tracking updates to reusable components over time.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: